diff options
33 files changed, 11079 insertions, 11006 deletions
diff --git a/docbook/GFDPL_appendix.xml b/docbook/GFDPL_appendix.xml index 658f4232ce..36a006dea5 100644 --- a/docbook/GFDPL_appendix.xml +++ b/docbook/GFDPL_appendix.xml @@ -1,443 +1,444 @@ -<!-- Ethereal GFDPL Appendix -->
-<appendix id="AppGFDL">
- <title>This Document's License (GFDL)</title>
- <section>
- <title>The GNU Free Document Public Licence</title>
- <section>
- <title>Copyright</title>
- <para>Version 1.1, March 2000 </para>
- <para>
- Copyright (C) 2000 Free Software Foundation, Inc.
- 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- Everyone is permitted to copy and distribute verbatim copies
- of this license document, but changing it is not allowed.
- </para>
- </section>
- <section>
- <title>Preamble</title>
- <para>
- The purpose of this License is to make a manual, textbook, or other
- written document "free" in the sense of freedom: to assure everyone
- the effective freedom to copy and redistribute it, with or without
- modifying it, either commercially or noncommercially. Secondarily,
- this License preserves for the author and publisher a way to get
- credit for their work, while not being considered responsible for
- modifications made by others.
- </para>
- <para>
- This License is a kind of "copyleft", which means that derivative
- works of the document must themselves be free in the same sense. It
- complements the GNU General Public License, which is a copyleft
- license designed for free software.
- </para>
- <para>
- We have designed this License in order to use it for manuals for free
- software, because free software needs free documentation: a free
- program should come with manuals providing the same freedoms that the
- software does. But this License is not limited to software manuals; it
- can be used for any textual work, regardless of subject matter or
- whether it is published as a printed book. We recommend this License
- principally for works whose purpose is instruction or reference.
- </para>
- </section>
- <section>
- <title>Applicability and Definitions</title>
- <para>
- This License applies to any manual or other work that contains a notice
- placed by the copyright holder saying it can be distributed under the
- terms of this License. The "Document", below, refers to any such
- manual or work. Any member of the public is a licensee, and is
- addressed as "you".
- </para>
- <para>
- A "Modified Version" of the Document means any work containing the
- Document or a portion of it, either copied verbatim, or with
- modifications and/or translated into another language.
- </para>
- <para>
- A "Secondary Section" is a named appendix or a front-matter section of
- the Document that deals exclusively with the relationship of the
- publishers or authors of the Document to the Document's overall subject
- (or to related matters) and contains nothing that could fall directly
- within that overall subject. (For example, if the Document is in part a
- textbook of mathematics, a Secondary Section may not explain any
- mathematics.) The relationship could be a matter of historical
- connection with the subject or with related matters, or of legal,
- commercial, philosophical, ethical or political position regarding them.
- </para>
- <para>
- The "Invariant Sections" are certain Secondary Sections whose titles
- are designated, as being those of Invariant Sections, in the notice
- that says that the Document is released under this License.
- </para>
- <para>
- The "Cover Texts" are certain short passages of text that are listed,
- as Front-Cover Texts or Back-Cover Texts, in the notice that says
- that the Document is released under this License.
- </para>
- <para>
- A "Transparent" copy of the Document means a machine-readable copy,
- represented in a format whose specification is available to the
- general public, whose contents can be viewed and edited directly
- and straightforwardly with generic text editors or (for images
- composed of pixels) generic paint programs or (for drawings) some
- widely available drawing editor, and that is suitable for input to
- text formatters or for automatic translation to a variety of
- formats suitable for input to text formatters. A copy made in an
- otherwise Transparent file format whose markup has been designed
- to thwart or discourage subsequent modification by readers is not
- Transparent. A copy that is not "Transparent" is called "Opaque".
- </para>
- <para>
- Examples of suitable formats for Transparent copies include plain
- ASCII without markup, Texinfo input format, LaTeX input format,
- SGML or XML using a publicly available DTD, and standard-conforming
- simple HTML designed for human modification. Opaque formats include
- PostScript, PDF, proprietary formats that can be read and edited
- only by proprietary word processors, SGML or XML for which the
- DTD and/or processing tools are not generally available, and the
- machine-generated HTML produced by some word processors for output
- purposes only.
- </para>
- <para>
- The "Title Page" means, for a printed book, the title page itself, plus
- such following pages as are needed to hold, legibly, the material this
- License requires to appear in the title page. For works in formats
- which do not have any title page as such, "Title Page" means the text
- near the most prominent appearance of the work's title,
- preceding the beginning of the body of the text.
- </para>
- </section>
- <section>
- <title>Verbatim Copying</title>
- <para>
- You may copy and distribute the Document in any medium, either
- commercially or noncommercially, provided that this License, the
- copyright notices, and the license notice saying this License
- applies to the Document are reproduced in all copies, and that you
- add no other conditions whatsoever to those of this License. You may
- not use technical measures to obstruct or control the reading or
- further copying of the copies you make or distribute. However, you
- may accept compensation in exchange for copies. If you distribute a
- large enough number of copies you must also follow the conditions
- in section 3.
- </para>
- <para>
- You may also lend copies, under the same conditions stated above, and
- you may publicly display copies.
- </para>
- </section>
- <section>
- <title>Copying in Quantity</title>
- <para>
- If you publish printed copies of the Document numbering more than 100,
- and the Document's license notice requires Cover Texts, you must
- enclose the copies in covers that carry, clearly and legibly, all
- these Cover Texts: Front-Cover Texts on the front cover, and
- Back-Cover Texts on the back cover. Both covers must also
- clearly and legibly identify you as the publisher of these copies. The
- front cover must present the full title with all words of the title
- equally prominent and visible. You may add other material on the
- covers in addition. Copying with changes limited to the covers,
- as long as they preserve the title of the Document and satisfy these
- conditions, can be treated as verbatim copying in other respects.
- </para>
- <para>
- If the required texts for either cover are too voluminous to fit
- legibly, you should put the first ones listed (as many as fit
- reasonably) on the actual cover, and continue
- the rest onto adjacent pages.
- </para>
- <para>
- If you publish or distribute Opaque copies of the Document numbering
- more than 100, you must either include a machine-readable Transparent
- copy along with each Opaque copy, or state in or with each Opaque
- copy a publicly-accessible computer-network location containing a
- complete Transparent copy of the Document, free of added material,
- which the general network-using public has access to download
- anonymously at no charge using public-standard network protocols. If
- you use the latter option, you must take reasonably prudent steps,
- when you begin distribution of Opaque copies in quantity, to ensure
- that this Transparent copy will remain thus accessible at the stated
- location until at least one year after the last time you distribute an
- Opaque copy (directly or through your agents or retailers) of that
- edition to the public.
- </para>
- <para>
- It is requested, but not required, that you contact the authors of the
- Document well before redistributing any large number of copies, to
- give them a chance to provide you with an updated version of the
- Document.
- </para>
- </section>
- <section>
- <title>Modifications</title>
- <para>
- You may copy and distribute a Modified Version of the Document under
- the conditions of sections 2 and 3 above, provided that you release
- the Modified Version under precisely this License, with the Modified
- Version filling the role of the Document, thus licensing distribution
- and modification of the Modified Version to whoever possesses a copy of
- it. In addition, you must do these things in the Modified Version:
- <itemizedlist>
- <listitem>
- <para>
- Use in the Title Page (and on the covers, if any) a title
- distinct from that of the Document, and from those of previous
- versions (which should, if there were any, be listed in the
- History section of the Document). You may use the same title as
- a previous version if the original publisher of that version gives
- permission.
- </para>
- </listitem>
- <listitem>
- <para>
- List on the Title Page, as authors, one or more persons or
- entities responsible for authorship of the modifications in the
- Modified Version, together with at least five of the principal
- authors of the Document (all of its principal authors,
- if it has less than five).
- </para>
- </listitem>
- <listitem>
- <para>
- State on the Title page the name of the publisher of the
- Modified Version, as the publisher.
- </para>
- </listitem>
- <listitem>
- <para>
- Preserve all the copyright notices of the Document.
- </para>
- </listitem>
- <listitem>
- <para>
- Add an appropriate copyright notice for your modifications
- adjacent to the other copyright notices.
- </para>
- </listitem>
- <listitem>
- <para>
- Include, immediately after the copyright notices, a license
- notice giving the public permission to use the Modified Version
- under the terms of this License, in the form shown in the
- Addendum below.
- </para>
- </listitem>
- <listitem>
- <para>
- Preserve in that license notice the full lists of Invariant
- Sections and required Cover Texts given in the Document's
- license notice.
- </para>
- </listitem>
- <listitem>
- <para>Include an unaltered copy of this License. </para>
- </listitem>
- <listitem>
- <para>
- Preserve the section entitled "History", and its title, and add
- to it an item stating at least the title, year, new authors,
- and publisher of the Modified Version as given on the Title
- Page. If there is no section entitled "History" in the
- Document, create one stating the title, year, authors,
- and publisher of the Document as given on its Title Page,
- then add an item describing the Modified Version as stated
- in the previous sentence.
- </para>
- </listitem>
- <listitem>
- <para>
- Preserve the network location, if any, given in the Document
- for public access to a Transparent copy of the Document, and
- likewise the network locations given in the Document for
- previous versions it was based on. These may be placed in
- the "History" section. You may omit a network location for a
- work that was published at least four years before the
- Document itself, or if the original publisher of the version
- it refers to gives permission.
- </para>
- </listitem>
- <listitem>
- <para>
- In any section entitled "Acknowledgements" or "Dedications",
- preserve the section's title, and preserve in the section all
- the substance and tone of each of the contributor
- acknowledgements and/or dedications given therein.
- </para>
- </listitem>
- <listitem>
- <para>
- Preserve all the Invariant Sections of the Document, unaltered
- in their text and in their titles. Section numbers or the
- equivalent are not considered part of the section titles.
- </para>
- </listitem>
- <listitem>
- <para>
- Delete any section entitled "Endorsements". Such a section
- may not be included in the Modified Version.
- </para>
- </listitem>
- <listitem>
- <para>
- Do not retitle any existing section as "Endorsements" or to
- conflict in title with any Invariant Section.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- If the Modified Version includes new front-matter sections or
- appendices that qualify as Secondary Sections and contain no
- material copied from the Document, you may at your option designate
- some or all of these sections as invariant. To do this, add their
- titles to the list of Invariant Sections in the Modified Version's
- license notice. These titles must be distinct from any other section
- titles.
- </para>
- <para>
- You may add a section entitled "Endorsements", provided it contains
- nothing but endorsements of your Modified Version by various
- parties--for example, statements of peer review or that the text has
- been approved by an organization as the authoritative definition of a
- standard.
- </para>
- <para>
- You may add a passage of up to five words as a Front-Cover Text,
- and a passage of up to 25 words as a Back-Cover Text, to the end
- of the list of Cover Texts in the Modified Version. Only one passage
- of Front-Cover Text and one of Back-Cover Text may be added by (or
- through arrangements made by) any one entity. If the Document
- already includes a cover text for the same cover, previously added
- by you or by arrangement made by the same entity you are acting on
- behalf of, you may not add another; but you may replace the old one,
- on explicit permission from the previous publisher that added the
- old one.
- </para>
- <para>
- The author(s) and publisher(s) of the Document do not by this
- License give permission to use their names for publicity for or to
- assert or imply endorsement of any Modified Version.
- </para>
- </section>
- <section>
- <title>Combining Documents</title>
- <para>
- You may combine the Document with other documents released under
- this License, under the terms defined in section 4 above for
- modified versions, provided that you include in the combination all
- of the Invariant Sections of all of the original documents,
- unmodified, and list them all as Invariant Sections of your combined
- work in its license notice.
- </para>
- <para>
- The combined work need only contain one copy of this License, and
- multiple identical Invariant Sections may be replaced with a single
- copy. If there are multiple Invariant Sections with the same name
- but different contents, make the title of each such section unique
- by adding at the end of it, in parentheses, the name of the
- original author or publisher of that section if known, or else a
- unique number. Make the same adjustment to the section titles in
- the list of Invariant Sections in the license notice of the combined
- work.
- </para>
- <para>
- In the combination, you must combine any sections entitled "History"
- in the various original documents, forming one section entitled
- "History"; likewise combine any sections entitled "Acknowledgements",
- and any sections entitled "Dedications". You must delete all
- sections entitled "Endorsements."
- </para>
- </section>
- <section>
- <title>Collections of Documents</title>
- <para>
- You may make a collection consisting of the Document and other
- documents released under this License, and replace the individual
- copies of this License in the various documents with a single copy
- that is included in the collection, provided that you follow the
- rules of this License for verbatim copying of each of the
- documents in all other respects.
- </para>
- <para>
- You may extract a single document from such a collection, and
- distribute it individually under this License, provided you insert a
- copy of this License into the extracted document, and follow this
- License in all other respects regarding verbatim copying of
- that document.
- </para>
- </section>
- <section>
- <title>Aggregation with Independent Works</title>
- <para>
- A compilation of the Document or its derivatives with other separate
- and independent documents or works, in or on a volume of a storage
- or distribution medium, does not as a whole count as a Modified
- Version of the Document, provided no compilation copyright is
- claimed for the compilation. Such a compilation is called an
- "aggregate", and this License does not apply to the other
- self-contained works thus compiled with the Document, on account
- of their being thus compiled, if they are not themselves derivative
- works of the Document.
- </para>
- <para>
- If the Cover Text requirement of section 3 is applicable to these
- copies of the Document, then if the Document is less than one quarter
- of the entire aggregate, the Document's Cover Texts may be placed
- on covers that surround only the Document within the aggregate.
- Otherwise they must appear on covers around the whole
- aggregate.
- </para>
- </section>
- <section>
- <title>Translation</title>
- <para>
- Translation is considered a kind of modification, so you may
- distribute translations of the Document under the terms of
- section 4. Replacing Invariant Sections with translations requires
- special permission from their copyright holders, but you may include
- translations of some or all Invariant Sections in addition to the
- original versions of these Invariant Sections. You may include a
- translation of this License provided that you also include the
- original English version of this License. In case
- of a disagreement between the translation and the original
- English version of this License, the original English version will
- prevail.
- </para>
- </section>
- <section>
- <title>Termination</title>
- <para>
- You may not copy, modify, sublicense, or distribute the Document
- except as expressly provided for under this License. Any other
- attempt to copy, modify, sublicense or distribute the Document is
- void, and will automatically terminate your rights under this
- License. However, parties who have received copies, or rights,
- from you under this License will not have their licenses terminated
- so long as such parties remain in full compliance.
- </para>
- </section>
- <section>
- <title>Future Revisions of this License</title>
- <para>
- The Free Software Foundation may publish new, revised versions of the
- GNU Free Documentation License from time to time. Such new versions
- will be similar in spirit to the present version, but may differ in
- detail to address new problems or concerns. See
- http://www.gnu.org/copyleft/.
- </para>
- <para>
- Each version of the License is given a distinguishing version
- number. If the Document specifies that a particular numbered
- version of this License "or any later version" applies to it, you
- have the option of following the terms and conditions either of
- that specified version or of any later version that has been
- published (not as a draft) by the Free Software Foundation. If
- the Document does not specify a version number of this License,
- you may choose any version ever published (not as a draft) by the
- Free Software Foundation.
- </para>
- </section>
- </section>
-</appendix>
+<!-- Ethereal GFDPL Appendix --> +<appendix id="AppGFDL"> +<!-- $Id$ --> + <title>This Document's License (GFDL)</title> + <section> + <title>The GNU Free Document Public Licence</title> + <section> + <title>Copyright</title> + <para>Version 1.1, March 2000 </para> + <para> + Copyright (C) 2000 Free Software Foundation, Inc. + 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + </para> + </section> + <section> + <title>Preamble</title> + <para> + The purpose of this License is to make a manual, textbook, or other + written document "free" in the sense of freedom: to assure everyone + the effective freedom to copy and redistribute it, with or without + modifying it, either commercially or noncommercially. Secondarily, + this License preserves for the author and publisher a way to get + credit for their work, while not being considered responsible for + modifications made by others. + </para> + <para> + This License is a kind of "copyleft", which means that derivative + works of the document must themselves be free in the same sense. It + complements the GNU General Public License, which is a copyleft + license designed for free software. + </para> + <para> + We have designed this License in order to use it for manuals for free + software, because free software needs free documentation: a free + program should come with manuals providing the same freedoms that the + software does. But this License is not limited to software manuals; it + can be used for any textual work, regardless of subject matter or + whether it is published as a printed book. We recommend this License + principally for works whose purpose is instruction or reference. + </para> + </section> + <section> + <title>Applicability and Definitions</title> + <para> + This License applies to any manual or other work that contains a notice + placed by the copyright holder saying it can be distributed under the + terms of this License. The "Document", below, refers to any such + manual or work. Any member of the public is a licensee, and is + addressed as "you". + </para> + <para> + A "Modified Version" of the Document means any work containing the + Document or a portion of it, either copied verbatim, or with + modifications and/or translated into another language. + </para> + <para> + A "Secondary Section" is a named appendix or a front-matter section of + the Document that deals exclusively with the relationship of the + publishers or authors of the Document to the Document's overall subject + (or to related matters) and contains nothing that could fall directly + within that overall subject. (For example, if the Document is in part a + textbook of mathematics, a Secondary Section may not explain any + mathematics.) The relationship could be a matter of historical + connection with the subject or with related matters, or of legal, + commercial, philosophical, ethical or political position regarding them. + </para> + <para> + The "Invariant Sections" are certain Secondary Sections whose titles + are designated, as being those of Invariant Sections, in the notice + that says that the Document is released under this License. + </para> + <para> + The "Cover Texts" are certain short passages of text that are listed, + as Front-Cover Texts or Back-Cover Texts, in the notice that says + that the Document is released under this License. + </para> + <para> + A "Transparent" copy of the Document means a machine-readable copy, + represented in a format whose specification is available to the + general public, whose contents can be viewed and edited directly + and straightforwardly with generic text editors or (for images + composed of pixels) generic paint programs or (for drawings) some + widely available drawing editor, and that is suitable for input to + text formatters or for automatic translation to a variety of + formats suitable for input to text formatters. A copy made in an + otherwise Transparent file format whose markup has been designed + to thwart or discourage subsequent modification by readers is not + Transparent. A copy that is not "Transparent" is called "Opaque". + </para> + <para> + Examples of suitable formats for Transparent copies include plain + ASCII without markup, Texinfo input format, LaTeX input format, + SGML or XML using a publicly available DTD, and standard-conforming + simple HTML designed for human modification. Opaque formats include + PostScript, PDF, proprietary formats that can be read and edited + only by proprietary word processors, SGML or XML for which the + DTD and/or processing tools are not generally available, and the + machine-generated HTML produced by some word processors for output + purposes only. + </para> + <para> + The "Title Page" means, for a printed book, the title page itself, plus + such following pages as are needed to hold, legibly, the material this + License requires to appear in the title page. For works in formats + which do not have any title page as such, "Title Page" means the text + near the most prominent appearance of the work's title, + preceding the beginning of the body of the text. + </para> + </section> + <section> + <title>Verbatim Copying</title> + <para> + You may copy and distribute the Document in any medium, either + commercially or noncommercially, provided that this License, the + copyright notices, and the license notice saying this License + applies to the Document are reproduced in all copies, and that you + add no other conditions whatsoever to those of this License. You may + not use technical measures to obstruct or control the reading or + further copying of the copies you make or distribute. However, you + may accept compensation in exchange for copies. If you distribute a + large enough number of copies you must also follow the conditions + in section 3. + </para> + <para> + You may also lend copies, under the same conditions stated above, and + you may publicly display copies. + </para> + </section> + <section> + <title>Copying in Quantity</title> + <para> + If you publish printed copies of the Document numbering more than 100, + and the Document's license notice requires Cover Texts, you must + enclose the copies in covers that carry, clearly and legibly, all + these Cover Texts: Front-Cover Texts on the front cover, and + Back-Cover Texts on the back cover. Both covers must also + clearly and legibly identify you as the publisher of these copies. The + front cover must present the full title with all words of the title + equally prominent and visible. You may add other material on the + covers in addition. Copying with changes limited to the covers, + as long as they preserve the title of the Document and satisfy these + conditions, can be treated as verbatim copying in other respects. + </para> + <para> + If the required texts for either cover are too voluminous to fit + legibly, you should put the first ones listed (as many as fit + reasonably) on the actual cover, and continue + the rest onto adjacent pages. + </para> + <para> + If you publish or distribute Opaque copies of the Document numbering + more than 100, you must either include a machine-readable Transparent + copy along with each Opaque copy, or state in or with each Opaque + copy a publicly-accessible computer-network location containing a + complete Transparent copy of the Document, free of added material, + which the general network-using public has access to download + anonymously at no charge using public-standard network protocols. If + you use the latter option, you must take reasonably prudent steps, + when you begin distribution of Opaque copies in quantity, to ensure + that this Transparent copy will remain thus accessible at the stated + location until at least one year after the last time you distribute an + Opaque copy (directly or through your agents or retailers) of that + edition to the public. + </para> + <para> + It is requested, but not required, that you contact the authors of the + Document well before redistributing any large number of copies, to + give them a chance to provide you with an updated version of the + Document. + </para> + </section> + <section> + <title>Modifications</title> + <para> + You may copy and distribute a Modified Version of the Document under + the conditions of sections 2 and 3 above, provided that you release + the Modified Version under precisely this License, with the Modified + Version filling the role of the Document, thus licensing distribution + and modification of the Modified Version to whoever possesses a copy of + it. In addition, you must do these things in the Modified Version: + <itemizedlist> + <listitem> + <para> + Use in the Title Page (and on the covers, if any) a title + distinct from that of the Document, and from those of previous + versions (which should, if there were any, be listed in the + History section of the Document). You may use the same title as + a previous version if the original publisher of that version gives + permission. + </para> + </listitem> + <listitem> + <para> + List on the Title Page, as authors, one or more persons or + entities responsible for authorship of the modifications in the + Modified Version, together with at least five of the principal + authors of the Document (all of its principal authors, + if it has less than five). + </para> + </listitem> + <listitem> + <para> + State on the Title page the name of the publisher of the + Modified Version, as the publisher. + </para> + </listitem> + <listitem> + <para> + Preserve all the copyright notices of the Document. + </para> + </listitem> + <listitem> + <para> + Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. + </para> + </listitem> + <listitem> + <para> + Include, immediately after the copyright notices, a license + notice giving the public permission to use the Modified Version + under the terms of this License, in the form shown in the + Addendum below. + </para> + </listitem> + <listitem> + <para> + Preserve in that license notice the full lists of Invariant + Sections and required Cover Texts given in the Document's + license notice. + </para> + </listitem> + <listitem> + <para>Include an unaltered copy of this License. </para> + </listitem> + <listitem> + <para> + Preserve the section entitled "History", and its title, and add + to it an item stating at least the title, year, new authors, + and publisher of the Modified Version as given on the Title + Page. If there is no section entitled "History" in the + Document, create one stating the title, year, authors, + and publisher of the Document as given on its Title Page, + then add an item describing the Modified Version as stated + in the previous sentence. + </para> + </listitem> + <listitem> + <para> + Preserve the network location, if any, given in the Document + for public access to a Transparent copy of the Document, and + likewise the network locations given in the Document for + previous versions it was based on. These may be placed in + the "History" section. You may omit a network location for a + work that was published at least four years before the + Document itself, or if the original publisher of the version + it refers to gives permission. + </para> + </listitem> + <listitem> + <para> + In any section entitled "Acknowledgements" or "Dedications", + preserve the section's title, and preserve in the section all + the substance and tone of each of the contributor + acknowledgements and/or dedications given therein. + </para> + </listitem> + <listitem> + <para> + Preserve all the Invariant Sections of the Document, unaltered + in their text and in their titles. Section numbers or the + equivalent are not considered part of the section titles. + </para> + </listitem> + <listitem> + <para> + Delete any section entitled "Endorsements". Such a section + may not be included in the Modified Version. + </para> + </listitem> + <listitem> + <para> + Do not retitle any existing section as "Endorsements" or to + conflict in title with any Invariant Section. + </para> + </listitem> + </itemizedlist> + </para> + <para> + If the Modified Version includes new front-matter sections or + appendices that qualify as Secondary Sections and contain no + material copied from the Document, you may at your option designate + some or all of these sections as invariant. To do this, add their + titles to the list of Invariant Sections in the Modified Version's + license notice. These titles must be distinct from any other section + titles. + </para> + <para> + You may add a section entitled "Endorsements", provided it contains + nothing but endorsements of your Modified Version by various + parties--for example, statements of peer review or that the text has + been approved by an organization as the authoritative definition of a + standard. + </para> + <para> + You may add a passage of up to five words as a Front-Cover Text, + and a passage of up to 25 words as a Back-Cover Text, to the end + of the list of Cover Texts in the Modified Version. Only one passage + of Front-Cover Text and one of Back-Cover Text may be added by (or + through arrangements made by) any one entity. If the Document + already includes a cover text for the same cover, previously added + by you or by arrangement made by the same entity you are acting on + behalf of, you may not add another; but you may replace the old one, + on explicit permission from the previous publisher that added the + old one. + </para> + <para> + The author(s) and publisher(s) of the Document do not by this + License give permission to use their names for publicity for or to + assert or imply endorsement of any Modified Version. + </para> + </section> + <section> + <title>Combining Documents</title> + <para> + You may combine the Document with other documents released under + this License, under the terms defined in section 4 above for + modified versions, provided that you include in the combination all + of the Invariant Sections of all of the original documents, + unmodified, and list them all as Invariant Sections of your combined + work in its license notice. + </para> + <para> + The combined work need only contain one copy of this License, and + multiple identical Invariant Sections may be replaced with a single + copy. If there are multiple Invariant Sections with the same name + but different contents, make the title of each such section unique + by adding at the end of it, in parentheses, the name of the + original author or publisher of that section if known, or else a + unique number. Make the same adjustment to the section titles in + the list of Invariant Sections in the license notice of the combined + work. + </para> + <para> + In the combination, you must combine any sections entitled "History" + in the various original documents, forming one section entitled + "History"; likewise combine any sections entitled "Acknowledgements", + and any sections entitled "Dedications". You must delete all + sections entitled "Endorsements." + </para> + </section> + <section> + <title>Collections of Documents</title> + <para> + You may make a collection consisting of the Document and other + documents released under this License, and replace the individual + copies of this License in the various documents with a single copy + that is included in the collection, provided that you follow the + rules of this License for verbatim copying of each of the + documents in all other respects. + </para> + <para> + You may extract a single document from such a collection, and + distribute it individually under this License, provided you insert a + copy of this License into the extracted document, and follow this + License in all other respects regarding verbatim copying of + that document. + </para> + </section> + <section> + <title>Aggregation with Independent Works</title> + <para> + A compilation of the Document or its derivatives with other separate + and independent documents or works, in or on a volume of a storage + or distribution medium, does not as a whole count as a Modified + Version of the Document, provided no compilation copyright is + claimed for the compilation. Such a compilation is called an + "aggregate", and this License does not apply to the other + self-contained works thus compiled with the Document, on account + of their being thus compiled, if they are not themselves derivative + works of the Document. + </para> + <para> + If the Cover Text requirement of section 3 is applicable to these + copies of the Document, then if the Document is less than one quarter + of the entire aggregate, the Document's Cover Texts may be placed + on covers that surround only the Document within the aggregate. + Otherwise they must appear on covers around the whole + aggregate. + </para> + </section> + <section> + <title>Translation</title> + <para> + Translation is considered a kind of modification, so you may + distribute translations of the Document under the terms of + section 4. Replacing Invariant Sections with translations requires + special permission from their copyright holders, but you may include + translations of some or all Invariant Sections in addition to the + original versions of these Invariant Sections. You may include a + translation of this License provided that you also include the + original English version of this License. In case + of a disagreement between the translation and the original + English version of this License, the original English version will + prevail. + </para> + </section> + <section> + <title>Termination</title> + <para> + You may not copy, modify, sublicense, or distribute the Document + except as expressly provided for under this License. Any other + attempt to copy, modify, sublicense or distribute the Document is + void, and will automatically terminate your rights under this + License. However, parties who have received copies, or rights, + from you under this License will not have their licenses terminated + so long as such parties remain in full compliance. + </para> + </section> + <section> + <title>Future Revisions of this License</title> + <para> + The Free Software Foundation may publish new, revised versions of the + GNU Free Documentation License from time to time. Such new versions + will be similar in spirit to the present version, but may differ in + detail to address new problems or concerns. See + http://www.gnu.org/copyleft/. + </para> + <para> + Each version of the License is given a distinguishing version + number. If the Document specifies that a particular numbered + version of this License "or any later version" applies to it, you + have the option of following the terms and conditions either of + that specified version or of any later version that has been + published (not as a draft) by the Free Software Foundation. If + the Document does not specify a version number of this License, + you may choose any version ever published (not as a draft) by the + Free Software Foundation. + </para> + </section> + </section> +</appendix> diff --git a/docbook/Makefile b/docbook/Makefile index 6113694856..df840da41c 100644 --- a/docbook/Makefile +++ b/docbook/Makefile @@ -1,101 +1,111 @@ -#
-# Make the "Ethereal User's Guide" in several formats.
-# See the Readme.txt file for instructions.
-#
-
-# if you need to change this, don't forget to change it in catalog.xml too
-DOCBOOKXSL="/usr/share/docbook-xsl"
-
-# formatting objects processor
-# (comment this out, if you don't want pdf or don't have fop installed)
-# for win32 (cygwin) environments
-FOP="fop-0.20.5/fop.bat"
-# for unix like environments (if you have problems with fop, try to use an absolute path here)
-#FOP="fop-0.20.5/fop.sh"
-
-# html help compiler (Win32 only)
-# (comment this out, if you don't want chm or don't have hhc installed)
-HHC="/cygdrive/c/Program Files/HTML Help Workshop/hhc.exe"
-
-############### YOU SHOULDN'T HAVE TO EDIT ANYTHING BELOW THIS LINE! ################
-
-# the XSL processor
-XSLTPROC="xsltproc"
-
-# the XML validator (from the xsltproc package)
-XMLLINT="xmllint"
-
-# as eug_chm will stop with an error, make sure it's the last in this dependency list
-all: eug_validate eug_pdf_a4 eug_html eug_html_chunked eug_chm
-
-clean:
- rm -f *.html
- rm -f htmlhelp.*
- rm -f *.hhc
- rm -f *.fo
- rm -f *.pdf
- rm -f *.chm
-
-images:
- cp $(DOCBOOKXSL)/images/note.png ./graphics
- cp $(DOCBOOKXSL)/images/tip.png ./graphics
- cp $(DOCBOOKXSL)/images/warning.png ./graphics
-
-# validate the content
-eug_validate:
- @ echo --- VALIDATING XML ---
- $(XMLLINT) --valid --noout user-guide.xml
-
-# create html single page file
-eug_html:
- @ echo --- HTML SINGLE PAGE ---
- mkdir -p eug_html
- mkdir -p eug_html/graphics
- mkdir -p eug_html/graphics/toolbar
- cp ./graphics/*.* eug_html/graphics
- cp ./graphics/toolbar/*.* eug_html/graphics/toolbar
- $(XSLTPROC) --nonet $(DOCBOOKXSL)/html/docbook.xsl user-guide.xml > eug_html/user-guide.html
-
-# create html chunked page files
-eug_html_chunked: images
- @ echo --- HTML CHUNKED ---
- mkdir -p eug_html_chunked
- mkdir -p eug_html_chunked/graphics
- mkdir -p eug_html_chunked/graphics/toolbar
- cp ./graphics/*.* eug_html_chunked/graphics
- cp ./graphics/toolbar/*.* eug_html_chunked/graphics/toolbar
- $(XSLTPROC) --stringparam base.dir eug_html_chunked/ --stringparam use.id.as.filename 1 --stringparam admon.graphics 1 --stringparam admon.graphics.path graphics/ --stringparam section.autolabel 1 --stringparam section.label.includes.component.label 1 --nonet $(DOCBOOKXSL)/html/chunk.xsl user-guide.xml
-
-# create pdf file (through XSL-FO), portrait pages on US letter paper (the default)
-# you will get lot's of errors, but that's ok
-eug_pdf_us: images
-ifdef FOP
- @ echo --- PDF US PAPER ---
- $(XSLTPROC) --nonet custom_layer_pdf.xsl $(DOCBOOKXSL)/fo/docbook.xsl user-guide.xml > user-guide.fo
- $(FOP) user-guide.fo user-guide.pdf
-endif
-
-# create pdf file (through XSL-FO), portrait pages on A4 paper
-# you will get lot's of errors, but that's ok
-eug_pdf_a4: images
-ifdef FOP
- @ echo --- PDF A4 PAPER ---
- $(XSLTPROC) --stringparam paper.type A4 --nonet custom_layer_pdf.xsl user-guide.xml > user-guide.fo
- $(FOP) user-guide.fo user-guide.pdf
-endif
-
-# create MS html help file (through html chunked pages)
-eug_chm: images
-ifdef HHC
- @ echo --- MICROSOFT HTML HELP ---
- mkdir -p eug_chm
- mkdir -p eug_chm/graphics
- mkdir -p eug_chm/graphics/toolbar
- cp ./graphics/*.* eug_chm/graphics
- cp ./graphics/toolbar/*.* eug_chm/graphics/toolbar
- $(XSLTPROC) --stringparam base.dir eug_chm/ --stringparam use.id.as.filename 1 --stringparam admon.graphics 1 --stringparam admon.graphics.path graphics/ --stringparam section.autolabel 1 --stringparam section.label.includes.component.label 1 --nonet $(DOCBOOKXSL)/htmlhelp/htmlhelp.xsl user-guide.xml
- -$(HHC) htmlhelp.hhp
- mv htmlhelp.chm user-guide.chm
- rm -r htmlhelp.hhp
- rm -r toc.hhc
-endif
+# +# Make the "Ethereal User's Guide" in several formats. +# See the Readme.txt file for instructions. +# +# $Id$ +# + +# if you need to change this, don't forget to change it in catalog.xml too + +# On suse 9.1, uncomment the following line: +#DOCBOOKXSL="/usr/share/xml/docbook/stylesheet/nwalsh/1.64.1" + +DOCBOOKXSL="/usr/share/docbook-xsl" + +# formatting objects processor +# (comment this out, if you don't want pdf or don't have fop installed) +# for win32 (cygwin) environments +FOP="fop-0.20.5/fop.bat" +# for unix like environments (if you have problems with fop, try to use an absolute path here) +#FOP="/usr/share/fop-0.20.5/fop.sh" + +# html help compiler (Win32 only) +# (comment this out, if you don't want chm or don't have hhc installed) +#HHC="/cygdrive/c/Program Files/HTML Help Workshop/hhc.exe" + +############### YOU SHOULDN'T HAVE TO EDIT ANYTHING BELOW THIS LINE! ################ + +# the XSL processor +XSLTPROC="xsltproc" + +# the XML validator (from the xsltproc package) +XMLLINT="xmllint" + +# as eug_chm will stop with an error, make sure it's the last in this dependency list +all: eug_validate eug_pdf_a4 eug_html eug_html_chunked eug_chm + +clean: + rm -f *.html + rm -f htmlhelp.* + rm -f *.hhc + rm -f *.fo + rm -f *.pdf + rm -f *.chm + rm -rf eug_html + rm -rf eug_html_chunked + rm -rf toc.hhc htmlhelp.hhp eug_chm + + +images: + cp $(DOCBOOKXSL)/images/note.png ./graphics + cp $(DOCBOOKXSL)/images/tip.png ./graphics + cp $(DOCBOOKXSL)/images/warning.png ./graphics + +# validate the content +eug_validate: + @ echo --- VALIDATING XML --- + $(XMLLINT) --valid --noout user-guide.xml + +# create html single page file +eug_html: + @ echo --- HTML SINGLE PAGE --- + mkdir -p eug_html + mkdir -p eug_html/graphics + mkdir -p eug_html/graphics/toolbar + cp ./graphics/*.* eug_html/graphics + cp ./graphics/toolbar/*.* eug_html/graphics/toolbar + $(XSLTPROC) --nonet $(DOCBOOKXSL)/html/docbook.xsl user-guide.xml > eug_html/user-guide.html + +# create html chunked page files +eug_html_chunked: images + @ echo --- HTML CHUNKED --- + mkdir -p eug_html_chunked + mkdir -p eug_html_chunked/graphics + mkdir -p eug_html_chunked/graphics/toolbar + cp ./graphics/*.* eug_html_chunked/graphics + cp ./graphics/toolbar/*.* eug_html_chunked/graphics/toolbar + $(XSLTPROC) --stringparam base.dir eug_html_chunked/ --stringparam use.id.as.filename 1 --stringparam admon.graphics 1 --stringparam admon.graphics.path graphics/ --stringparam section.autolabel 1 --stringparam section.label.includes.component.label 1 --nonet $(DOCBOOKXSL)/html/chunk.xsl user-guide.xml + +# create pdf file (through XSL-FO), portrait pages on US letter paper (the default) +# you will get lot's of errors, but that's ok +eug_pdf_us: images +ifdef FOP + @ echo --- PDF US PAPER --- + $(XSLTPROC) --nonet custom_layer_pdf.xsl $(DOCBOOKXSL)/fo/docbook.xsl user-guide.xml > user-guide.fo + $(FOP) user-guide.fo user-guide.pdf +endif + +# create pdf file (through XSL-FO), portrait pages on A4 paper +# you will get lot's of errors, but that's ok +eug_pdf_a4: images +ifdef FOP + @ echo --- PDF A4 PAPER --- + $(XSLTPROC) --stringparam paper.type A4 --nonet custom_layer_pdf.xsl user-guide.xml > user-guide.fo + $(FOP) user-guide.fo user-guide.pdf +endif + +# create MS html help file (through html chunked pages) +eug_chm: images +ifdef HHC + @ echo --- MICROSOFT HTML HELP --- + mkdir -p eug_chm + mkdir -p eug_chm/graphics + mkdir -p eug_chm/graphics/toolbar + cp ./graphics/*.* eug_chm/graphics + cp ./graphics/toolbar/*.* eug_chm/graphics/toolbar + $(XSLTPROC) --stringparam base.dir eug_chm/ --stringparam use.id.as.filename 1 --stringparam admon.graphics 1 --stringparam admon.graphics.path graphics/ --stringparam section.autolabel 1 --stringparam section.label.includes.component.label 1 --nonet $(DOCBOOKXSL)/htmlhelp/htmlhelp.xsl user-guide.xml + -$(HHC) htmlhelp.hhp + mv htmlhelp.chm user-guide.chm + rm -r htmlhelp.hhp + rm -r toc.hhc +endif diff --git a/docbook/README.txt b/docbook/README.txt index 10eb1ebe86..00d9b2d737 100644 --- a/docbook/README.txt +++ b/docbook/README.txt @@ -1,135 +1,137 @@ -This directory contains the source files needed to build the:
-
-Ethereal User's guide (almost ready to release, has to be reviewed)
-
-and the:
-
-Ethereal Developer's Guide (long time unchanged still a very early state).
-
-To build the User's Guide, just do 'make', but see requirements below.
-The Developer's Guide is currently not generated, as it has no content.
-
-
-The guides are written in Docbook/XML (formerly Docbook/SGML). This format is
-now used by many other documentation projects, e.g. "the linux documentation
-project" uses it too.
-
-To get HTML, PDF or other output formats, conversions are done using XSL
-stylesheets, which provides a flexible way for these conversions.
-
-The current Makefile is running under Win32 in the cygwin environment, so it uses
-GNU make and such. It should be pretty easy to use it in UNIX environments too.
-Using Microsoft make (nmake) is not supported.
-
-By default the Makefile generates HTML in single page and multiple (chunked) formats.
-Optional output formats are PDF and CHM.
-
-
-Requirements:
--------------
-
-Settings in Makefile and catalog.xml
-------------------------------------
-You have to edit the settings in these files, to point to the DTD/XSL files, fop (and possibly hhc).
-
-DocBook XML DTD
----------------
-DocBook "official" XML DTD V4.2 from:
-http://www.oasis-open.org/docbook/xml/
-(or using cygwin package docbook-xml42)
-
-DocBook XSL
------------
-The "official" XSL stylesheets from Norman Walsh:
-http://docbook.sourceforge.net/
-(or using cygwin package docbook-xsl)
-
-xsltproc
---------
-The XSL processor xsltproc.
-(it seems to be packages libxml2 and libxslt, ... please give comments)
-
-FOP processor (for PDF generation only)
----------------------------------------
-FOP processor from the apache project:
-http://xml.apache.org/fop/
-FOP is a JAVA program, so you need to have a JAVA environment installed.
-I have put the fop-0.20.5 dir right into the sources dir. If you have it somewhere else,
-you'll have to change the setting in the Makefile.
-
-Be sure to also have installed JAI and/or jimi to be able to use/convert the png graphics files.
-The fop release note webpage tells how to do it:
-download jimi from:
-http://java.sun.com/products/jimi/
-then extract the archive, then copy JimiProClasses.zip to FOP's lib dir and rename it to jimi-1.0.jar.
-
-As I got OutOfMemoryException when running fop, I had to insert -Xmx256m into the last line of the fop.bat file from:
-java -cp "%LOCALCLASSPATH%" org.apache.fop.apps.Fop %1 %2 %3 %4 %5 %6 %7 %8
-to:
-java -Xmx256m -cp "%LOCALCLASSPATH%" org.apache.fop.apps.Fop %1 %2 %3 %4 %5 %6 %7 %8
-
-HTML help compiler (for chm file generation only)
--------------------------------------------------
-hhc compiler from Microsoft:
-http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hwMicrosoftHTMLHelpDownloads.asp
-
-
-Makefile:
----------
-There are several ways and tools to do these conversion, following is a short
-description of the way the makefile targets are doing things and which output
-files required for a release in that format.
-
-all
-Will generate all output formats (see below).
-
-make eug_html
-The HTML file is generated using xsltproc and the XSL stylesheets from
-Norman Walsh. This is a conversion into a single HTML page.
-output: eug_html
-
-make eug_htmlchunk
-The HTML files are generated using xsltproc and the XSL stylesheets from
-Norman Walsh. This is a conversion into chunked (multiple) HTML pages.
-output: eug_html_chunked
-
-make eug_pdf_us
-make eug_pdf_a4
-The PDF is generated using an intermediate format named XSL-FO (XSL
-formatting objects). xsltproc converts the XML to a FO file, and then fop
-(apache's formatting object processor) is used to generate the PDF document,
-in US letter or A4 paper format.
-TIPP: You will get lot's of INFO/WARNING/ERROR messages when generating pdf,
-but conversation works just fine.
-output: user-guide.pdf
-
-make eug_chm
-On Win32 platforms, the "famous" HTML help format can be generated by using a
-special HTML chunked conversion and then use the htmlhelp compiler from
-Microsoft.
-output: htmlhelp.chm
-
-The makefile is written to be run with gmake on unix/linux platforms. Win32
-platforms have to use the cygwin environment (Microsoft nmake is not
-supported).
-
-
-Docbook web references:
------------------------
-Some web references to further documentation about Docbook/XML and Docbook XSL conversions:
-
-DocBook: The Definitive Guide
-by Norman Walsh and Leonard Muellner
-http://www.docbook.org/tdg/en/html/docbook.html
-
-DocBook XSL: The Complete Guide
-by Bob Stayton
-http://www.sagehill.net/docbookxsl/index.html
-
-Documention with DocBook on Win32
-by Jim Crafton
-http://www.codeproject.com/winhelp/docbook_howto.asp
-
-FO Parameter Reference
-by Norman Walsh
-http://docbook.sourceforge.net/release/xsl/current/doc/fo/
+$Id$ + +This directory contains the source files needed to build the: + +Ethereal User's guide (almost ready to release, has to be reviewed) + +and the: + +Ethereal Developer's Guide (long time unchanged still a very early state). + +To build the User's Guide, just do 'make', but see requirements below. +The Developer's Guide is currently not generated, as it has no content. + + +The guides are written in Docbook/XML (formerly Docbook/SGML). This format is +now used by many other documentation projects, e.g. "the linux documentation +project" uses it too. + +To get HTML, PDF or other output formats, conversions are done using XSL +stylesheets, which provides a flexible way for these conversions. + +The current Makefile is running under Win32 in the cygwin environment, so it uses +GNU make and such. It should be pretty easy to use it in UNIX environments too. +Using Microsoft make (nmake) is not supported. + +By default the Makefile generates HTML in single page and multiple (chunked) formats. +Optional output formats are PDF and CHM. + + +Requirements: +------------- + +Settings in Makefile and catalog.xml +------------------------------------ +You have to edit the settings in these files, to point to the DTD/XSL files, fop (and possibly hhc). + +DocBook XML DTD +--------------- +DocBook "official" XML DTD V4.2 from: +http://www.oasis-open.org/docbook/xml/ +(or using cygwin package docbook-xml42) + +DocBook XSL +----------- +The "official" XSL stylesheets from Norman Walsh: +http://docbook.sourceforge.net/ +(or using cygwin package docbook-xsl) + +xsltproc +-------- +The XSL processor xsltproc. +(it seems to be packages libxml2 and libxslt, ... please give comments) + +FOP processor (for PDF generation only) +--------------------------------------- +FOP processor from the apache project: +http://xml.apache.org/fop/ +FOP is a JAVA program, so you need to have a JAVA environment installed. +I have put the fop-0.20.5 dir right into the sources dir. If you have it somewhere else, +you'll have to change the setting in the Makefile. + +Be sure to also have installed JAI and/or jimi to be able to use/convert the png graphics files. +The fop release note webpage tells how to do it: +download jimi from: +http://java.sun.com/products/jimi/ +then extract the archive, then copy JimiProClasses.zip to FOP's lib dir and rename it to jimi-1.0.jar. + +As I got OutOfMemoryException when running fop, I had to insert -Xmx256m into the last line of the fop.bat file from: +java -cp "%LOCALCLASSPATH%" org.apache.fop.apps.Fop %1 %2 %3 %4 %5 %6 %7 %8 +to: +java -Xmx256m -cp "%LOCALCLASSPATH%" org.apache.fop.apps.Fop %1 %2 %3 %4 %5 %6 %7 %8 + +HTML help compiler (for chm file generation only) +------------------------------------------------- +hhc compiler from Microsoft: +http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hwMicrosoftHTMLHelpDownloads.asp + + +Makefile: +--------- +There are several ways and tools to do these conversion, following is a short +description of the way the makefile targets are doing things and which output +files required for a release in that format. + +all +Will generate all output formats (see below). + +make eug_html +The HTML file is generated using xsltproc and the XSL stylesheets from +Norman Walsh. This is a conversion into a single HTML page. +output: eug_html + +make eug_htmlchunk +The HTML files are generated using xsltproc and the XSL stylesheets from +Norman Walsh. This is a conversion into chunked (multiple) HTML pages. +output: eug_html_chunked + +make eug_pdf_us +make eug_pdf_a4 +The PDF is generated using an intermediate format named XSL-FO (XSL +formatting objects). xsltproc converts the XML to a FO file, and then fop +(apache's formatting object processor) is used to generate the PDF document, +in US letter or A4 paper format. +TIPP: You will get lot's of INFO/WARNING/ERROR messages when generating pdf, +but conversation works just fine. +output: user-guide.pdf + +make eug_chm +On Win32 platforms, the "famous" HTML help format can be generated by using a +special HTML chunked conversion and then use the htmlhelp compiler from +Microsoft. +output: htmlhelp.chm + +The makefile is written to be run with gmake on unix/linux platforms. Win32 +platforms have to use the cygwin environment (Microsoft nmake is not +supported). + + +Docbook web references: +----------------------- +Some web references to further documentation about Docbook/XML and Docbook XSL conversions: + +DocBook: The Definitive Guide +by Norman Walsh and Leonard Muellner +http://www.docbook.org/tdg/en/html/docbook.html + +DocBook XSL: The Complete Guide +by Bob Stayton +http://www.sagehill.net/docbookxsl/index.html + +Documention with DocBook on Win32 +by Jim Crafton +http://www.codeproject.com/winhelp/docbook_howto.asp + +FO Parameter Reference +by Norman Walsh +http://docbook.sourceforge.net/release/xsl/current/doc/fo/ diff --git a/docbook/catalog.xml b/docbook/catalog.xml index 07acfa8e50..f90c46b5b4 100644 --- a/docbook/catalog.xml +++ b/docbook/catalog.xml @@ -1,56 +1,58 @@ -<?xml version="1.0"?>
-<!-- Ethereal User's Guide and Developer's Guide catalog
-
+<?xml version="1.0"?> +<!-- Ethereal User's Guide and Developer's Guide catalog + $Id$ + See the Readme.txt file for instructions. Please note that if you shift any files in the directory structure you MUST adjust this catalog. --->
-<!DOCTYPE catalog
- PUBLIC "-//OASIS/DTD Entity Resolution XML Catalog V1.0//EN"
- "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">
-
-<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
-
- <!-- DTD and stylesheet files installed under /usr/share/xml -->
- <group xml:base="file:///usr/share/xml/" >
-
- <!-- Resolve DTD URL system ID to local file -->
- <rewriteSystem
- systemIdStartString="http://www.oasis-open.org/docbook/xml/4.2/"
- rewritePrefix="/usr/share/docbook-xml42/" />
- <!-- Resolve stylesheet URL to local file -->
- <!-- if you need to change this, don't forget to change it in the Makefile too -->
- <rewriteURI
- uriStartString="http://docbook.sourceforge.net/release/xsl/current/"
- rewritePrefix="/usr/share/docbook-xsl/" />
-
- <!-- Resolve DTD PUBLIC identifiers -->
- <nextCatalog catalog="docbook42/catalog.xml" />
-
- <!-- To resolve simple DTD SYSTEM identifiers. -->
- <!-- Note: this does not work with Java resolver -->
- <!-- classes in Saxon or Xalan -->
- <system
- systemId="docbook.dtd"
- uri="docbook42/docbookx.dtd" />
- - <!-- To resolve short stylesheet references -->
- <!--
- <system
- systemId="EtherealMain1"
- uri="./graphics/ethereal-main.jpg" />
- <system
- systemId="EtherealThreePane1"
- uri="./graphics/ethereal-main.jpg" />
- <uri
- name="chunk.xsl"
- uri="docbook-xsl-1.62.1/html/chunk.xsl" />
- <uri
- name="fo-docbook.xsl"
- uri="docbook-xsl-1.62.1/fo/docbook.xsl" />
- -->
-
- </group>
-
-</catalog>
\ No newline at end of file +--> +<!DOCTYPE catalog + PUBLIC "-//OASIS/DTD Entity Resolution XML Catalog V1.0//EN" + "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd"> + +<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"> + + <!-- DTD and stylesheet files installed under /usr/share/xml --> + <group xml:base="file:///usr/share/xml/" > + + <!-- Resolve DTD URL system ID to local file --> + <rewriteSystem + systemIdStartString="http://www.oasis-open.org/docbook/xml/4.2/" + rewritePrefix="/usr/share/docbook-xml42/" /> + <!-- Resolve stylesheet URL to local file --> + <!-- if you need to change this, don't forget to change it in the Makefile too --> + <rewriteURI + uriStartString="http://docbook.sourceforge.net/release/xsl/current/" + rewritePrefix="/usr/share/docbook-xsl/" /> + <!-- rewritePrefix="/usr/share/xml/docbook/stylesheet/nwalsh/1.64.1/" /> --> + + <!-- Resolve DTD PUBLIC identifiers --> + <nextCatalog catalog="docbook42/catalog.xml" /> + + <!-- To resolve simple DTD SYSTEM identifiers. --> + <!-- Note: this does not work with Java resolver --> + <!-- classes in Saxon or Xalan --> + <system + systemId="docbook.dtd" + uri="docbook42/docbookx.dtd" /> + + <!-- To resolve short stylesheet references --> + <!-- + <system + systemId="EtherealMain1" + uri="./graphics/ethereal-main.jpg" /> + <system + systemId="EtherealThreePane1" + uri="./graphics/ethereal-main.jpg" /> + <uri + name="chunk.xsl" + uri="docbook-xsl-1.62.1/html/chunk.xsl" /> + <uri + name="fo-docbook.xsl" + uri="docbook-xsl-1.62.1/fo/docbook.xsl" /> + --> + + </group> + +</catalog> diff --git a/docbook/custom_layer_pdf.xsl b/docbook/custom_layer_pdf.xsl index b8904efe97..decca391dd 100644 --- a/docbook/custom_layer_pdf.xsl +++ b/docbook/custom_layer_pdf.xsl @@ -1,36 +1,38 @@ -<?xml version='1.0'?>
-<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
- version="1.0">
+<?xml version='1.0'?> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + version="1.0"> + +<!-- $Id$ --> <!-- import the main stylesheet --> -<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/fo/docbook.xsl"/>
-
-<!-- create pdf bookmarks -->
-<xsl:param name="fop.extensions" select="1"/>
-
-<!-- use graphics for admons (note, tip, ...) -->
-<xsl:param name="admon.graphics" select="1"/>
-<xsl:param name="admon.graphics.path">graphics/</xsl:param>
-
-<!-- use numbering for sections (not only for chapters) -->
-<xsl:param name="section.autolabel" select="1"/>
-<xsl:param name="section.label.includes.component.label" select="1"/>
-
-<!-- include page numbers in cross references -->
-<!-- <xsl:param name="insert.xref.page.number" select="1"/> -->
-
-<!-- don't show URL's, but only the text of it -->
-<xsl:param name="ulink.show" select="0"/>
-
+<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/fo/docbook.xsl"/> + +<!-- create pdf bookmarks --> +<xsl:param name="fop.extensions" select="1"/> + +<!-- use graphics for admons (note, tip, ...) --> +<xsl:param name="admon.graphics" select="1"/> +<xsl:param name="admon.graphics.path">graphics/</xsl:param> + +<!-- use numbering for sections (not only for chapters) --> +<xsl:param name="section.autolabel" select="1"/> +<xsl:param name="section.label.includes.component.label" select="1"/> + +<!-- include page numbers in cross references --> +<!-- <xsl:param name="insert.xref.page.number" select="1"/> --> + +<!-- don't show URL's, but only the text of it --> +<xsl:param name="ulink.show" select="0"/> + <!-- put a page break after each section --> -<xsl:attribute-set name="section.level1.properties">
- <xsl:attribute name="break-after">page</xsl:attribute>
+<xsl:attribute-set name="section.level1.properties"> + <xsl:attribute name="break-after">page</xsl:attribute> </xsl:attribute-set> -<!-- set link style to blue and underlined -->
-<xsl:attribute-set name="xref.properties">
+<!-- set link style to blue and underlined --> +<xsl:attribute-set name="xref.properties"> <xsl:attribute name="color">blue</xsl:attribute> - <xsl:attribute name="text-decoration">underline</xsl:attribute>
-</xsl:attribute-set>
-
+ <xsl:attribute name="text-decoration">underline</xsl:attribute> +</xsl:attribute-set> + </xsl:stylesheet> diff --git a/docbook/developer-guide.xml b/docbook/developer-guide.xml index fc2f72493a..40c604c663 100644 --- a/docbook/developer-guide.xml +++ b/docbook/developer-guide.xml @@ -1,76 +1,78 @@ -<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
-
-<!--
-BIOGRAPHICAL SECTION
--Use this section to encode all biographical information
--->
-
-<!-- Authors Names -->
- <!ENTITY AuthorFullName "Richard Sharpe">
- <!ENTITY AuthorFirstName "Richard">
- <!ENTITY AuthorOtherName "">
- <!ENTITY AuthorSurname "Sharpe">
-
-<!--Authors Affiliation -->
- <!ENTITY AuthorShortAffiliation "">
- <!ENTITY AuthorJobTitle "Director">
- <!ENTITY AuthorOrgName "NS Computer Software and Services P/L">
- <!ENTITY AuthorOrgDiv "">
-
-<!--
-DOCUMENT SECTION
--Use this section to encode all document information
--->
-
- <!ENTITY DocumentTitle "<application>Ethereal</application> Developer's Guide">
- <!ENTITY DocumentSubTitle "">
- <!ENTITY DocumentTitleAbbreviation "EDG">
-
- <!ENTITY DocumentCopyrightHolder "NS Computer Software and Services P/L">
- <!ENTITY DocumentCopyrightYear "2000">
-
- <!ENTITY DocumentEdition "First edition">
- <!ENTITY DocumentPubDate "2000">
-
- <!ENTITY DocumentLegalNotice "<para>Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. A copy of the license is included in the section entitled "GNU Free Documentation License"</para>">
-
-<!--
-Ethereal Info
--->
- <!ENTITY EtherealCurrentVersion "0.8.10">
- <!ENTITY EtherealNextMinorVersion "0.8.11">
-
-<!--
-FILE SECTION
--Use this section to specify the files that make up the book. Use FPI (public identifiers)
--->
-
-
-<!-- These are the actual files that make up the document -->
- <!ENTITY BookMetaInformation SYSTEM "dg-src/EDG_meta_info.xml">
- <!ENTITY Chapter1 SYSTEM "dg-src/EDG_chapter_one.xml">
- <!ENTITY Chapter2 SYSTEM "dg-src/EDG_chapter_two.xml">
- <!ENTITY Chapter3 SYSTEM "dg-src/EDG_chapter_three.xml">
- <!ENTITY Chapter4 SYSTEM "dg-src/EDG_chapter_four.xml">
- <!ENTITY Chapter5 SYSTEM "dg-src/EDG_chapter_five.xml">
-
-<!-- These refer to graphics files and figures contained in the document -->
- <!-- 1st Chapter -->
-]>
-
-<book>
-<title>&DocumentTitle;</title>
-<subtitle>&DocumentSubTitle;</subtitle>
-&BookMetaInformation;
-&Chapter1;
-&Chapter2;
-&Chapter3;
-&Chapter4;
-&Chapter5;
-<!--
-
-&Glossary;
-&Index; -->
-</book>
+<?xml version="1.0"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ + +<!-- $Id$ --> + +<!-- +BIOGRAPHICAL SECTION +-Use this section to encode all biographical information +--> + +<!-- Authors Names --> + <!ENTITY AuthorFullName "Richard Sharpe"> + <!ENTITY AuthorFirstName "Richard"> + <!ENTITY AuthorOtherName ""> + <!ENTITY AuthorSurname "Sharpe"> + +<!--Authors Affiliation --> + <!ENTITY AuthorShortAffiliation ""> + <!ENTITY AuthorJobTitle "Director"> + <!ENTITY AuthorOrgName "NS Computer Software and Services P/L"> + <!ENTITY AuthorOrgDiv ""> + +<!-- +DOCUMENT SECTION +-Use this section to encode all document information +--> + + <!ENTITY DocumentTitle "<application>Ethereal</application> Developer's Guide"> + <!ENTITY DocumentSubTitle ""> + <!ENTITY DocumentTitleAbbreviation "EDG"> + + <!ENTITY DocumentCopyrightHolder "NS Computer Software and Services P/L"> + <!ENTITY DocumentCopyrightYear "2000"> + + <!ENTITY DocumentEdition "First edition"> + <!ENTITY DocumentPubDate "2000"> + + <!ENTITY DocumentLegalNotice "<para>Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. A copy of the license is included in the section entitled "GNU Free Documentation License"</para>"> + +<!-- +Ethereal Info +--> + <!ENTITY EtherealCurrentVersion "0.8.10"> + <!ENTITY EtherealNextMinorVersion "0.8.11"> + +<!-- +FILE SECTION +-Use this section to specify the files that make up the book. Use FPI (public identifiers) +--> + + +<!-- These are the actual files that make up the document --> + <!ENTITY BookMetaInformation SYSTEM "dg-src/EDG_meta_info.xml"> + <!ENTITY Chapter1 SYSTEM "dg-src/EDG_chapter_one.xml"> + <!ENTITY Chapter2 SYSTEM "dg-src/EDG_chapter_two.xml"> + <!ENTITY Chapter3 SYSTEM "dg-src/EDG_chapter_three.xml"> + <!ENTITY Chapter4 SYSTEM "dg-src/EDG_chapter_four.xml"> + <!ENTITY Chapter5 SYSTEM "dg-src/EDG_chapter_five.xml"> + +<!-- These refer to graphics files and figures contained in the document --> + <!-- 1st Chapter --> +]> + +<book> +<title>&DocumentTitle;</title> +<subtitle>&DocumentSubTitle;</subtitle> +&BookMetaInformation; +&Chapter1; +&Chapter2; +&Chapter3; +&Chapter4; +&Chapter5; +<!-- + +&Glossary; +&Index; --> +</book> diff --git a/docbook/dfilter2xml.pl b/docbook/dfilter2xml.pl index e150820613..a2e6971215 100644 --- a/docbook/dfilter2xml.pl +++ b/docbook/dfilter2xml.pl @@ -1,153 +1,153 @@ -#!/usr/bin/perl
-#
-# Reads the display filter keyword dump produced by 'ethereal -G' and
-# formats it for a pod document. The pod document is then used to
-# make a manpage
-#
-# STDIN is the ethereal glossary
-# arg1 is the pod template file. The =insert_dfilter_table token
-# will be replaced by the pod-formatted glossary
-# STDOUT is the output
-#
-# $Id: dfilter2sgml,v 1.5 2002/09/10 15:49:57 sharpe Exp $
-
-%ftenum_names = (
- 'FT_NONE', 'No value',
- 'FT_PROTOCOL', 'Protocol',
- 'FT_BOOLEAN', 'Boolean',
- 'FT_UINT8', 'Unsigned 8-bit integer',
- 'FT_UINT16', 'Unsigned 16-bit integer',
- 'FT_UINT24', 'Unsigned 24-bit integer',
- 'FT_UINT32', 'Unsigned 32-bit integer',
- 'FT_UINT64', 'Unsigned 64-bit integer',
- 'FT_INT8', 'Signed 8-bit integer',
- 'FT_INT16', 'Signed 16-bit integer',
- 'FT_INT24', 'Signed 24-bit integer',
- 'FT_INT32', 'Signed 32-bit integer',
- 'FT_INT64', 'Signed 64-bit integer',
- 'FT_DOUBLE', 'Double-precision floating point',
- 'FT_ABSOLUTE_TIME', 'Date/Time stamp',
- 'FT_RELATIVE_TIME', 'Time duration',
- 'FT_STRING', 'String',
- 'FT_STRINGZ', 'String',
- 'FT_UINT_STRING', 'String',
- 'FT_ETHER', '6-byte Hardware (MAC) Address',
- 'FT_BYTES', 'Byte array',
- 'FT_IPv4', 'IPv4 address',
- 'FT_IPv6', 'IPv6 address',
- 'FT_IPXNET', 'IPX network or server name',
-);
-
-# Read all the data into memory
-while (<STDIN>) {
- next unless (/^([PF])/);
-
- $record_type = $1;
- chomp($_);
- $_ =~ s/\&/\&\;/g;
- $_ =~ s/\>/\>/g;
- $_ =~ s/\</\<\;/g;
-
- # Store protocol information
- if ($record_type eq 'P') {
- ($junk, $name, $abbrev) = split(/\t+/, $_);
- $proto_abbrev{$name} = $abbrev;
- }
- # Store header field information
- else {
- ($junk, $name, $abbrev, $type, $parent, $blurb) =
- split(/\t+/, $_);
- push(@{$field_abbrev{$parent}}, $abbrev);
- $field_info{$abbrev} = [ $name, $type, $blurb ];
- }
-}
-
-# if there was no input on stdin, bail out
-if ($record_type ne 'P' and $record_type ne 'F') {
- exit;
-}
-
-$template = shift(@ARGV);
-
-open(TEMPLATE, $template) || die "Can't open $template for reading: $!\n";
-
-while (<TEMPLATE>) {
- if (/=insert_dfilter_table/) {
- &create_dfilter_table;
- }
- else {
- print;
- }
-}
-
-close(TEMPLATE) || die "Can't close $template: $!\n";
-
-sub create_dfilter_table {
-
- print "<appendix id=\"AppFiltFields\"><title>Ethereal Display Filter Fields</title>\n";
- $pn_counter = 1;
-
- # Print each protocol
- for $proto_name (sort keys %proto_abbrev) {
-
- $ns_proto_name = $proto_name;
- $ns_proto_name =~ s/\s//g;
- $ns_proto_name =~ s/\)//g;
- $ns_proto_name =~ s/\(//g;
- $ns_proto_name =~ s/_//g;
- $ns_proto_name =~ s/\+/plus/g;
- $ns_proto_name =~ s/\//slash/g;
- $ns_proto_name =~ s/,/comma/g;
- $ns_proto_name =~ s/:/colon/g;
- $ns_proto_name =~ s/'/apos/g;
-
- # The maximum token name length is apparently 44 characters.
- # That's what NAMELEN is defined as in docbook 4.1, at least.
-
- if (length ($ns_proto_name) > 41) { # "SID" and "TID" are prepended below
- $ns_proto_name = sprintf ("%s%04d", substr($ns_proto_name, 0,
- 37), $pn_counter);
- $pn_counter++;
- }
-
- print "<section id=\"SID$ns_proto_name\"><title>$proto_name ($proto_abbrev{$proto_name})</title>\n\n";
-
- print "<table id=\"TID$ns_proto_name\"><title>$proto_name ($proto_abbrev{$proto_name})</title>\n";
- print "<tgroup cols=\"4\">\n";
-# print "<colspec colnum=\"1\" colwidth=\"80pt\">\n";
-# print "<colspec colnum=\"2\" colwidth=\"80pt\"\n>";
- print "<thead>\n <row>\n ";
- print "<entry>Field</>\n <entry>Field Name</>\n <entry>Type</>\n <entry>Description</>\n\n";
-
- print " </row>\n</thead>\n<tbody>\n";
-
- # If this proto has children fields, print those
- if ($field_abbrev{$proto_abbrev{$proto_name}}) {
-
- for $field_abbrev (sort @{$field_abbrev{$proto_abbrev{$proto_name}}}) {
-
- print " <row>\n";
- print " <entry>$field_abbrev</entry>\n";
- print " <entry>", $field_info{$field_abbrev}[0], "</entry>\n";
- print " <entry>", $ftenum_names{$field_info{$field_abbrev}[1]}, "</entry>\n";
- print " <entry>", $field_info{$field_abbrev}[2], "</>\n";
- print " </row>\n\n";
-
- }
-
- }
- else {
-
- print " <row>\n <entry></entry>\n <entry></entry>\n <entry></entry><entry></entry>\n";
- print " </row>\n";
-
- }
-
- print "</tbody></tgroup></table>\n";
- print "</section>\n\n";
-
- }
-
- print "</appendix>\n";
-
-}
+#!/usr/bin/perl +# +# Reads the display filter keyword dump produced by 'ethereal -G' and +# formats it for a pod document. The pod document is then used to +# make a manpage +# +# STDIN is the ethereal glossary +# arg1 is the pod template file. The =insert_dfilter_table token +# will be replaced by the pod-formatted glossary +# STDOUT is the output +# +# $Id$ + +%ftenum_names = ( + 'FT_NONE', 'No value', + 'FT_PROTOCOL', 'Protocol', + 'FT_BOOLEAN', 'Boolean', + 'FT_UINT8', 'Unsigned 8-bit integer', + 'FT_UINT16', 'Unsigned 16-bit integer', + 'FT_UINT24', 'Unsigned 24-bit integer', + 'FT_UINT32', 'Unsigned 32-bit integer', + 'FT_UINT64', 'Unsigned 64-bit integer', + 'FT_INT8', 'Signed 8-bit integer', + 'FT_INT16', 'Signed 16-bit integer', + 'FT_INT24', 'Signed 24-bit integer', + 'FT_INT32', 'Signed 32-bit integer', + 'FT_INT64', 'Signed 64-bit integer', + 'FT_DOUBLE', 'Double-precision floating point', + 'FT_ABSOLUTE_TIME', 'Date/Time stamp', + 'FT_RELATIVE_TIME', 'Time duration', + 'FT_STRING', 'String', + 'FT_STRINGZ', 'String', + 'FT_UINT_STRING', 'String', + 'FT_ETHER', '6-byte Hardware (MAC) Address', + 'FT_BYTES', 'Byte array', + 'FT_IPv4', 'IPv4 address', + 'FT_IPv6', 'IPv6 address', + 'FT_IPXNET', 'IPX network or server name', +); + +# Read all the data into memory +while (<STDIN>) { + next unless (/^([PF])/); + + $record_type = $1; + chomp($_); + $_ =~ s/\&/\&\;/g; + $_ =~ s/\>/\>/g; + $_ =~ s/\</\<\;/g; + + # Store protocol information + if ($record_type eq 'P') { + ($junk, $name, $abbrev) = split(/\t+/, $_); + $proto_abbrev{$name} = $abbrev; + } + # Store header field information + else { + ($junk, $name, $abbrev, $type, $parent, $blurb) = + split(/\t+/, $_); + push(@{$field_abbrev{$parent}}, $abbrev); + $field_info{$abbrev} = [ $name, $type, $blurb ]; + } +} + +# if there was no input on stdin, bail out +if ($record_type ne 'P' and $record_type ne 'F') { + exit; +} + +$template = shift(@ARGV); + +open(TEMPLATE, $template) || die "Can't open $template for reading: $!\n"; + +while (<TEMPLATE>) { + if (/=insert_dfilter_table/) { + &create_dfilter_table; + } + else { + print; + } +} + +close(TEMPLATE) || die "Can't close $template: $!\n"; + +sub create_dfilter_table { + + print "<appendix id=\"AppFiltFields\"><title>Ethereal Display Filter Fields</title>\n"; + $pn_counter = 1; + + # Print each protocol + for $proto_name (sort keys %proto_abbrev) { + + $ns_proto_name = $proto_name; + $ns_proto_name =~ s/\s//g; + $ns_proto_name =~ s/\)//g; + $ns_proto_name =~ s/\(//g; + $ns_proto_name =~ s/_//g; + $ns_proto_name =~ s/\+/plus/g; + $ns_proto_name =~ s/\//slash/g; + $ns_proto_name =~ s/,/comma/g; + $ns_proto_name =~ s/:/colon/g; + $ns_proto_name =~ s/'/apos/g; + + # The maximum token name length is apparently 44 characters. + # That's what NAMELEN is defined as in docbook 4.1, at least. + + if (length ($ns_proto_name) > 41) { # "SID" and "TID" are prepended below + $ns_proto_name = sprintf ("%s%04d", substr($ns_proto_name, 0, + 37), $pn_counter); + $pn_counter++; + } + + print "<section id=\"SID$ns_proto_name\"><title>$proto_name ($proto_abbrev{$proto_name})</title>\n\n"; + + print "<table id=\"TID$ns_proto_name\"><title>$proto_name ($proto_abbrev{$proto_name})</title>\n"; + print "<tgroup cols=\"4\">\n"; +# print "<colspec colnum=\"1\" colwidth=\"80pt\">\n"; +# print "<colspec colnum=\"2\" colwidth=\"80pt\"\n>"; + print "<thead>\n <row>\n "; + print "<entry>Field</>\n <entry>Field Name</>\n <entry>Type</>\n <entry>Description</>\n\n"; + + print " </row>\n</thead>\n<tbody>\n"; + + # If this proto has children fields, print those + if ($field_abbrev{$proto_abbrev{$proto_name}}) { + + for $field_abbrev (sort @{$field_abbrev{$proto_abbrev{$proto_name}}}) { + + print " <row>\n"; + print " <entry>$field_abbrev</entry>\n"; + print " <entry>", $field_info{$field_abbrev}[0], "</entry>\n"; + print " <entry>", $ftenum_names{$field_info{$field_abbrev}[1]}, "</entry>\n"; + print " <entry>", $field_info{$field_abbrev}[2], "</>\n"; + print " </row>\n\n"; + + } + + } + else { + + print " <row>\n <entry></entry>\n <entry></entry>\n <entry></entry><entry></entry>\n"; + print " </row>\n"; + + } + + print "</tbody></tgroup></table>\n"; + print "</section>\n\n"; + + } + + print "</appendix>\n"; + +} diff --git a/docbook/dg-src/EDG_chapter_five.xml b/docbook/dg-src/EDG_chapter_five.xml index 3f6cc7b529..50e36ff20d 100644 --- a/docbook/dg-src/EDG_chapter_five.xml +++ b/docbook/dg-src/EDG_chapter_five.xml @@ -1,12 +1,14 @@ -<!-- EDG Chapter Five -->
-<chapter id="Chap05">
-<title>Functions available to dissector writers</title>
-<section>
-<title>Groups 1</title>
-<para>
-<application>Ethereal</application> is perhaps one of blah blah...
-</para>
-</section>
-
-</chapter>
-<!-- End of EDG Chapter 5 -->
+<!-- EDG Chapter Five --> +<!-- $Id$--> + +<chapter id="Chap05"> +<title>Functions available to dissector writers</title> +<section> +<title>Groups 1</title> +<para> +<application>Ethereal</application> is perhaps one of blah blah... +</para> +</section> + +</chapter> +<!-- End of EDG Chapter 5 --> diff --git a/docbook/dg-src/EDG_chapter_four.xml b/docbook/dg-src/EDG_chapter_four.xml index 83c00bb86c..9808922f62 100644 --- a/docbook/dg-src/EDG_chapter_four.xml +++ b/docbook/dg-src/EDG_chapter_four.xml @@ -1,33 +1,35 @@ -<!-- EDG Chapter Four -->
-<chapter id="Chap04">
-<title>Writing a new dissector by example</title>
-<section>
-<title>Introduction</title>
-<para>
-<application>Ethereal</application> is perhaps one of blah blah...
-</para>
-</section>
-
-<section>
-<title>Producing the code</title>
-<para>Another para</para>
-</section>
-
-<section>
-<title>The files you have to create and modify</title>
-<para>A para</para>
-</section>
-
-<section>
-<title>Running autoconf.sh</title>
-<para>A para</para>
-</section>
-
-<section>
-<title>Contributing your new dissector</title>
-<para>A para</para>
-</section>
-
-</chapter>
-<!-- End of EDG Chapter 4 -->
-
+<!-- EDG Chapter Four --> +<!-- $Id$ --> + +<chapter id="Chap04"> +<title>Writing a new dissector by example</title> +<section> +<title>Introduction</title> +<para> +<application>Ethereal</application> is perhaps one of blah blah... +</para> +</section> + +<section> +<title>Producing the code</title> +<para>Another para</para> +</section> + +<section> +<title>The files you have to create and modify</title> +<para>A para</para> +</section> + +<section> +<title>Running autoconf.sh</title> +<para>A para</para> +</section> + +<section> +<title>Contributing your new dissector</title> +<para>A para</para> +</section> + +</chapter> +<!-- End of EDG Chapter 4 --> + diff --git a/docbook/dg-src/EDG_chapter_one.xml b/docbook/dg-src/EDG_chapter_one.xml index b9d74bf941..9e4ca79458 100644 --- a/docbook/dg-src/EDG_chapter_one.xml +++ b/docbook/dg-src/EDG_chapter_one.xml @@ -1,39 +1,41 @@ -<!-- EDG Chapter One -->
-<chapter id="Chap01">
-<title>Introduction</title>
- <!-- Introduction -->
-<section>
-<title>What is <application>Ethereal?</application></title>
-<para>
-<application>Ethereal</application> is perhaps one of blah blah...
-</para>
-</section>
-
-<section>
-<title>A rose by any other name</title>
-<para>One more</para>
-</section>
-
-<section>
-<title>A brief history of Ethereal</title>
-<para>One para</para>
-</section>
-
-<section>
-<title>Platforms Ethereal runs on</title>
-<para>One para</para>
-
-</section>
-
-<section>
-<title>Where to get Ethereal</title>
-<para>Another para</para>
-</section>
-
-<section>
-<title>Where to get the latest copy of this document</title>
-<para>Another para</para>
-</section>
-
-</chapter>
-<!-- End of EDG Chapter 1 -->
+<!-- EDG Chapter One --> +<!-- $Id$ --> + +<chapter id="Chap01"> +<title>Introduction</title> + <!-- Introduction --> +<section> +<title>What is <application>Ethereal?</application></title> +<para> +<application>Ethereal</application> is perhaps one of blah blah... +</para> +</section> + +<section> +<title>A rose by any other name</title> +<para>One more</para> +</section> + +<section> +<title>A brief history of Ethereal</title> +<para>One para</para> +</section> + +<section> +<title>Platforms Ethereal runs on</title> +<para>One para</para> + +</section> + +<section> +<title>Where to get Ethereal</title> +<para>Another para</para> +</section> + +<section> +<title>Where to get the latest copy of this document</title> +<para>Another para</para> +</section> + +</chapter> +<!-- End of EDG Chapter 1 --> diff --git a/docbook/dg-src/EDG_chapter_three.xml b/docbook/dg-src/EDG_chapter_three.xml index 4850eedf7f..6ba526eb29 100644 --- a/docbook/dg-src/EDG_chapter_three.xml +++ b/docbook/dg-src/EDG_chapter_three.xml @@ -1,34 +1,36 @@ -<!-- EDG Chapter Three -->
-<chapter id="Chap03">
-<title>How Ethereal works</title>
-<section>
-<title>Introduction</title>
-<para>
-<application>Ethereal</application> is perhaps one of blah blah...
-</para>
-</section>
-
-<section>
-<title>Capturing packets</title>
-<!-- Including Windows versions -->
-<para>Another para</para>
-</section>
-
-<section>
-<title>Passes across the data</title>
-<para>Another para</para>
-</section>
-
-<section>
-<title>Calling the dissection routines</title>
-<para>Another para</para>
-
-</section>
-
-<section>
-<title>Parameters passed</title>
-<para>Another para</para>
-</section>
-
-</chapter>
-<!-- End of EDG Chapter 3 -->
+<!-- EDG Chapter Three --> +<!-- $Id$ --> + +<chapter id="Chap03"> +<title>How Ethereal works</title> +<section> +<title>Introduction</title> +<para> +<application>Ethereal</application> is perhaps one of blah blah... +</para> +</section> + +<section> +<title>Capturing packets</title> +<!-- Including Windows versions --> +<para>Another para</para> +</section> + +<section> +<title>Passes across the data</title> +<para>Another para</para> +</section> + +<section> +<title>Calling the dissection routines</title> +<para>Another para</para> + +</section> + +<section> +<title>Parameters passed</title> +<para>Another para</para> +</section> + +</chapter> +<!-- End of EDG Chapter 3 --> diff --git a/docbook/dg-src/EDG_chapter_two.xml b/docbook/dg-src/EDG_chapter_two.xml index e6177d0da0..6e9e9eaf28 100644 --- a/docbook/dg-src/EDG_chapter_two.xml +++ b/docbook/dg-src/EDG_chapter_two.xml @@ -1,33 +1,35 @@ -<!-- EDG Chapter Two -->
-<chapter id="Chap02">
-<title>What is packet sniffing</title>
-<section>
-<title>Introduction</title>
-<para>
-<application>Ethereal</application> is perhaps one of blah blah...
-</para>
-</section>
-
-<section>
-<title>tcpdump, libpcap and other tools</title>
-<para>A para here</para>
-</section>
-
-<section>
-<title>The structure of packets</title>
-<para>Another para</para>
-</section>
-
-<section>
-<title>How a packet's payload is handled</title>
-<para>Another para</para>
-
-</section>
-
-<section>
-<title>An introduction to wiretap</title>
-<para>Another para</para>
-</section>
-
-</chapter>
-<!-- End of EDG Chapter 2 -->
+<!-- EDG Chapter Two --> +<!-- $Id$ --> + +<chapter id="Chap02"> +<title>What is packet sniffing</title> +<section> +<title>Introduction</title> +<para> +<application>Ethereal</application> is perhaps one of blah blah... +</para> +</section> + +<section> +<title>tcpdump, libpcap and other tools</title> +<para>A para here</para> +</section> + +<section> +<title>The structure of packets</title> +<para>Another para</para> +</section> + +<section> +<title>How a packet's payload is handled</title> +<para>Another para</para> + +</section> + +<section> +<title>An introduction to wiretap</title> +<para>Another para</para> +</section> + +</chapter> +<!-- End of EDG Chapter 2 --> diff --git a/docbook/dg-src/EDG_meta_info.xml b/docbook/dg-src/EDG_meta_info.xml index 2e367c7c3b..5c73da86e3 100644 --- a/docbook/dg-src/EDG_meta_info.xml +++ b/docbook/dg-src/EDG_meta_info.xml @@ -1,19 +1,21 @@ -<bookinfo>
- <title>&DocumentTitle;</title>
- <subtitle>&DocumentSubTitle;</subtitle>
- <authorgroup>
- <author><firstname>&AuthorFirstName;</firstname><surname>&AuthorSurname;</surname>
- <affiliation><orgname>&AuthorOrgName;</orgname></affiliation>
- </author>
- </authorgroup>
- <edition>&DocumentEdition;</edition>
- <pubdate>&DocumentPubDate;</pubdate>
- <copyright><year>&DocumentCopyrightYear;</year>
- <holder>&DocumentCopyrightHolder;</holder>
- </copyright>
-
-<legalnotice>
- &DocumentLegalNotice;
-</legalnotice>
-
-</bookinfo>
+<!-- $Id$ --> + +<bookinfo> + <title>&DocumentTitle;</title> + <subtitle>&DocumentSubTitle;</subtitle> + <authorgroup> + <author><firstname>&AuthorFirstName;</firstname><surname>&AuthorSurname;</surname> + <affiliation><orgname>&AuthorOrgName;</orgname></affiliation> + </author> + </authorgroup> + <edition>&DocumentEdition;</edition> + <pubdate>&DocumentPubDate;</pubdate> + <copyright><year>&DocumentCopyrightYear;</year> + <holder>&DocumentCopyrightHolder;</holder> + </copyright> + +<legalnotice> + &DocumentLegalNotice; +</legalnotice> + +</bookinfo> diff --git a/docbook/ethereal-doc.txt b/docbook/ethereal-doc.txt index 4a09b56d17..d9a58e83ca 100644 --- a/docbook/ethereal-doc.txt +++ b/docbook/ethereal-doc.txt @@ -1,93 +1,95 @@ -ETHEREAL USER'S GUIDE OUTLINE
-
-Chapter 1.0 Introduction
- - What is Ethereal
- - A rose by any other name
- - A brief history of Ethereal
- - Platforms Ethereal runs on
- - Where to get Ethereal
-
-Chapter 2.0 Building and Installing Ethereal
- - Obtaining the source and binary distributions
- - Before you build Ethereal
- - Building the source
- - Installing the binaries
- - Installing from RPMs
-
-Chapter 3.0 Using Ethereal
- - Starting Ethereal
- - Capturing packets
- - Filtering during capturing
- - Viewing packets
- - Viewing packets while you capture
- - Saving captures
- - Reading captures from other tools
- - Filtering packets while viewing
-
-Chapter 4.0 Troubleshooting with Ethereal
-
- - An approach to troubleshooting with Ethereal
- - Examples of troubleshooting
-
-Chapter 5.0 Miscellaneous topics
-
- - Capturing with tcpdump for viewing with Ethereal
- - Using editpcap
- - Other tools
-
-Glossary
-
-Index
-
-ETHEREAL DEVELOPERS GUIDE OUTLINE
-
-1.0 Introduction
-
- - What is Ethereal
- - A rose by any other name
- - A brief history of Ethereal
- - Platforms Ethereal runs on
- - Where to get Ethereal
-
-2.0 What is packet sniffing
-
- - The use of libpcap and other capture tools
- - The structure of packets
- - How a packet's payload is handled
- - An introduction to wiretap
-
-3.0 An outline of what Ethereal does
-
- - Capturing packets
- - Passes across the data
- - Calling the dissection routines
- - Parameters passed
-
-4.0 Writing a new dissector by example
-
- - The basics of writing a dissector
- - Producing the code
- - The files you have to produce and modify
- - Running autoconf.sh
- - The final product
- - Contributing your new dissector
-
-5.0 Functions avalailable to dissector writers
-
- - All the relevant functions
-
-6.0 A list of all the existing dissectors
-
- - A list of all the dissectors
-
-Glossary
-
-Index
-
-Regards
--------
-Richard Sharpe, sharpe@ns.aus.com
-Samba (Team member, www.samba.org), Ethereal (Team member, www.zing.org)
-
-
-
+$Id$ + +ETHEREAL USER'S GUIDE OUTLINE + +Chapter 1.0 Introduction + - What is Ethereal + - A rose by any other name + - A brief history of Ethereal + - Platforms Ethereal runs on + - Where to get Ethereal + +Chapter 2.0 Building and Installing Ethereal + - Obtaining the source and binary distributions + - Before you build Ethereal + - Building the source + - Installing the binaries + - Installing from RPMs + +Chapter 3.0 Using Ethereal + - Starting Ethereal + - Capturing packets + - Filtering during capturing + - Viewing packets + - Viewing packets while you capture + - Saving captures + - Reading captures from other tools + - Filtering packets while viewing + +Chapter 4.0 Troubleshooting with Ethereal + + - An approach to troubleshooting with Ethereal + - Examples of troubleshooting + +Chapter 5.0 Miscellaneous topics + + - Capturing with tcpdump for viewing with Ethereal + - Using editpcap + - Other tools + +Glossary + +Index + +ETHEREAL DEVELOPERS GUIDE OUTLINE + +1.0 Introduction + + - What is Ethereal + - A rose by any other name + - A brief history of Ethereal + - Platforms Ethereal runs on + - Where to get Ethereal + +2.0 What is packet sniffing + + - The use of libpcap and other capture tools + - The structure of packets + - How a packet's payload is handled + - An introduction to wiretap + +3.0 An outline of what Ethereal does + + - Capturing packets + - Passes across the data + - Calling the dissection routines + - Parameters passed + +4.0 Writing a new dissector by example + + - The basics of writing a dissector + - Producing the code + - The files you have to produce and modify + - Running autoconf.sh + - The final product + - Contributing your new dissector + +5.0 Functions avalailable to dissector writers + + - All the relevant functions + +6.0 A list of all the existing dissectors + + - A list of all the dissectors + +Glossary + +Index + +Regards +------- +Richard Sharpe, sharpe@ns.aus.com +Samba (Team member, www.samba.org), Ethereal (Team member, www.zing.org) + + + diff --git a/docbook/protocols.xml b/docbook/protocols.xml index bd5b8d3aad..269ee76f1b 100644 --- a/docbook/protocols.xml +++ b/docbook/protocols.xml @@ -1,327 +1,329 @@ -<itemizedlist id="EtherealListOfProtos">
- <listitem><para>802.1q Virtual LAN</para></listitem>
- <listitem><para>802.1x Authentication</para></listitem>
- <listitem><para>AFS (4.0) Replication Server call declarations</para></listitem>
- <listitem><para>AOL Instant Messenger</para></listitem>
- <listitem><para>ATM</para></listitem>
- <listitem><para>ATM LAN Emulation</para></listitem>
- <listitem><para>Ad hoc On-demand Distance Vector Routing Protocol</para></listitem>
- <listitem><para>Ad hoc On-demand Distance Vector Routing Protocol v6</para></listitem>
- <listitem><para>Address Resolution Protocol</para></listitem>
- <listitem><para>Aggregate Server Access Protocol</para></listitem>
- <listitem><para>Andrew File System (AFS)</para></listitem>
- <listitem><para>Apache JServ Protocol v1.3</para></listitem>
- <listitem><para>AppleTalk Filing Protocol</para></listitem>
- <listitem><para>AppleTalk Session Protocol</para></listitem>
- <listitem><para>AppleTalk Transaction Protocol packet</para></listitem>
- <listitem><para>Appletalk Address Resolution Protocol</para></listitem>
- <listitem><para>Async data over ISDN (V.120)</para></listitem>
- <listitem><para>Authentication Header</para></listitem>
- <listitem><para>BACnet Virtual Link Control</para></listitem>
- <listitem><para>Banyan Vines</para></listitem>
- <listitem><para>Banyan Vines Fragmentation Protocol</para></listitem>
- <listitem><para>Banyan Vines SPP</para></listitem>
- <listitem><para>Blocks Extensible Exchange Protocol</para></listitem>
- <listitem><para>Boot Parameters</para></listitem>
- <listitem><para>Bootstrap Protocol</para></listitem>
- <listitem><para>Border Gateway Protocol</para></listitem>
- <listitem><para>Building Automation and Control Network APDU</para></listitem>
- <listitem><para>Building Automation and Control Network NPDU</para></listitem>
- <listitem><para>CDS Clerk Server Calls</para></listitem>
- <listitem><para>Check Point High Availability Protocol</para></listitem>
- <listitem><para>Checkpoint FW-1</para></listitem>
- <listitem><para>Cisco Auto-RP</para></listitem>
- <listitem><para>Cisco Discovery Protocol</para></listitem>
- <listitem><para>Cisco Group Management Protocol</para></listitem>
- <listitem><para>Cisco HDLC</para></listitem>
- <listitem><para>Cisco Hot Standby Router Protocol</para></listitem>
- <listitem><para>Cisco ISL</para></listitem>
- <listitem><para>Cisco Interior Gateway Routing Protocol</para></listitem>
- <listitem><para>Cisco NetFlow</para></listitem>
- <listitem><para>Cisco SLARP</para></listitem>
- <listitem><para>CoSine IPNOS L2 debug output</para></listitem>
- <listitem><para>Common Open Policy Service</para></listitem>
- <listitem><para>Common Unix Printing System (CUPS) Browsing Protocol</para></listitem>
- <listitem><para>DCE DFS Calls</para></listitem>
- <listitem><para>DCE Name Service</para></listitem>
- <listitem><para>DCE RPC</para></listitem>
- <listitem><para>DCE Security ID Mapper</para></listitem>
- <listitem><para>DCE/RPC BOS Server</para></listitem>
- <listitem><para>DCE/RPC CDS Solicitation</para></listitem>
- <listitem><para>DCE/RPC Conversation Manager</para></listitem>
- <listitem><para>DCE/RPC Endpoint Mapper</para></listitem>
- <listitem><para>DCE/RPC FLDB</para></listitem>
- <listitem><para>DCE/RPC FLDB UBIK TRANSFER</para></listitem>
- <listitem><para>DCE/RPC Kerberos V</para></listitem>
- <listitem><para>DCE/RPC RS_ACCT</para></listitem>
- <listitem><para>DCE/RPC RS_MISC</para></listitem>
- <listitem><para>DCE/RPC RS_UNIX</para></listitem>
- <listitem><para>DCE/RPC Remote Management</para></listitem>
- <listitem><para>DCE/RPC Repserver Calls</para></listitem>
- <listitem><para>DCE/RPC TokenServer Calls</para></listitem>
- <listitem><para>DCOM OXID Resolver</para></listitem>
- <listitem><para>DCOM Remote Activation</para></listitem>
- <listitem><para>DEC Spanning Tree Protocol</para></listitem>
- <listitem><para>DHCPv6</para></listitem>
- <listitem><para>DNS Control Program Server</para></listitem>
- <listitem><para>Data</para></listitem>
- <listitem><para>Data Link SWitching</para></listitem>
- <listitem><para>Data Stream Interface</para></listitem>
- <listitem><para>Datagram Delivery Protocol</para></listitem>
- <listitem><para>Diameter Protocol</para></listitem>
- <listitem><para>Distance Vector Multicast Routing Protocol</para></listitem>
- <listitem><para>Distributed Checksum Clearinghouse Prototocl</para></listitem>
- <listitem><para>Domain Name Service</para></listitem>
- <listitem><para>Dummy Protocol</para></listitem>
- <listitem><para>Dynamic DNS Tools Protocol</para></listitem>
- <listitem><para>Encapsulating Security Payload</para></listitem>
- <listitem><para>Enhanced Interior Gateway Routing Protocol</para></listitem>
- <listitem><para>Ethernet</para></listitem>
- <listitem><para>Extensible Authentication Protocol</para></listitem>
- <listitem><para>FTP Data</para></listitem>
- <listitem><para>FTServer Operations</para></listitem>
- <listitem><para>Fiber Distributed Data Interface</para></listitem>
- <listitem><para>File Transfer Protocol (FTP)</para></listitem>
- <listitem><para>Financial Information eXchange Protocol</para></listitem>
- <listitem><para>Frame</para></listitem>
- <listitem><para>Frame Relay</para></listitem>
- <listitem><para>GARP Multicast Registration Protocol</para></listitem>
- <listitem><para>GARP VLAN Registration Protocol</para></listitem>
- <listitem><para>GPRS Tunneling Protocol</para></listitem>
- <listitem><para>GPRS Tunnelling Protocol v0</para></listitem>
- <listitem><para>GPRS Tunnelling Protocol v1</para></listitem>
- <listitem><para>General Inter-ORB Protocol</para></listitem>
- <listitem><para>Generic Routing Encapsulation</para></listitem>
- <listitem><para>Generic Security Service Application Program Interface</para></listitem>
- <listitem><para>Gnutella Protocol</para></listitem>
- <listitem><para>Hummingbird NFS Daemon</para></listitem>
- <listitem><para>Hypertext Transfer Protocol</para></listitem>
- <listitem><para>ICQ Protocol</para></listitem>
- <listitem><para>IEEE 802.11 wireless LAN</para></listitem>
- <listitem><para>IEEE 802.11 wireless LAN management frame</para></listitem>
- <listitem><para>ILMI</para></listitem>
- <listitem><para>IP Payload Compression</para></listitem>
- <listitem><para>IPX Message</para></listitem>
- <listitem><para>IPX Routing Information Protocol</para></listitem>
- <listitem><para>ISDN Q.921-User Adaptation Layer</para></listitem>
- <listitem><para>ISDN User Part</para></listitem>
- <listitem><para>ISO 10589 ISIS InTRA Domain Routeing Information Exchange Protocol</para></listitem>
- <listitem><para>ISO 8073 COTP Connection-Oriented Transport Protocol</para></listitem>
- <listitem><para>ISO 8473 CLNP ConnectionLess Network Protocol</para></listitem>
- <listitem><para>ISO 8602 CLTP ConnectionLess Transport Protocol</para></listitem>
- <listitem><para>ISO 9542 ESIS Routeing Information Exchange Protocol</para></listitem>
- <listitem><para>ITU-T Recommendation H.261</para></listitem>
- <listitem><para>Inter-Access-Point Protocol</para></listitem>
- <listitem><para>Interbase</para></listitem>
- <listitem><para>Internet Cache Protocol</para></listitem>
- <listitem><para>Internet Content Adaptation Protocol</para></listitem>
- <listitem><para>Internet Control Message Protocol</para></listitem>
- <listitem><para>Internet Control Message Protocol v6</para></listitem>
- <listitem><para>Internet Group Management Protocol</para></listitem>
- <listitem><para>Internet Message Access Protocol</para></listitem>
- <listitem><para>Internet Printing Protocol</para></listitem>
- <listitem><para>Internet Protocol</para></listitem>
- <listitem><para>Internet Protocol Version 6</para></listitem>
- <listitem><para>Internet Relay Chat</para></listitem>
- <listitem><para>Internet Security Association and Key Management Protocol</para></listitem>
- <listitem><para>Internetwork Packet eXchange</para></listitem>
- <listitem><para>Java RMI</para></listitem>
- <listitem><para>Java Serialization</para></listitem>
- <listitem><para>Kerberos</para></listitem>
- <listitem><para>Kernel Lock Manager</para></listitem>
- <listitem><para>Label Distribution Protocol</para></listitem>
- <listitem><para>Layer 2 Tunneling Protocol</para></listitem>
- <listitem><para>Lightweight Directory Access Protocol</para></listitem>
- <listitem><para>Line Printer Daemon Protocol</para></listitem>
- <listitem><para>Link Access Procedure Balanced (LAPB)</para></listitem>
- <listitem><para>Link Access Procedure Balanced Ethernet (LAPBETHER)</para></listitem>
- <listitem><para>Link Access Procedure, Channel D (LAPD)</para></listitem>
- <listitem><para>Link Aggregation Control Protocol</para></listitem>
- <listitem><para>Link Management Protocol (LMP)</para></listitem>
- <listitem><para>Linux cooked-mode capture</para></listitem>
- <listitem><para>Local Management Interface</para></listitem>
- <listitem><para>LocalTalk Link Access Protocol</para></listitem>
- <listitem><para>Logical-Link Control</para></listitem>
- <listitem><para>Lucent/Ascend debug output</para></listitem>
- <listitem><para>MMS Message Encapsulation</para></listitem>
- <listitem><para>MS Proxy Protocol</para></listitem>
- <listitem><para>MSNIP: Multicast Source Notification of Interest Protocol</para></listitem>
- <listitem><para>MTP 2 Transparent Proxy</para></listitem>
- <listitem><para>MTP 2 User Adaptation Layer</para></listitem>
- <listitem><para>MTP 3 User Adaptation Layer</para></listitem>
- <listitem><para>MTP2 Peer Adaptation Layer</para></listitem>
- <listitem><para>Malformed Packet</para></listitem>
- <listitem><para>Message Transfer Part Level 2</para></listitem>
- <listitem><para>Message Transfer Part Level 3</para></listitem>
- <listitem><para>Microsoft Distributed File System</para></listitem>
- <listitem><para>Microsoft Exchange MAPI</para></listitem>
- <listitem><para>Microsoft Local Security Architecture</para></listitem>
- <listitem><para>Microsoft Network Logon</para></listitem>
- <listitem><para>Microsoft Registry</para></listitem>
- <listitem><para>Microsoft Security Account Manager</para></listitem>
- <listitem><para>Microsoft Server Service</para></listitem>
- <listitem><para>Microsoft Spool Subsystem</para></listitem>
- <listitem><para>Microsoft Telephony API Service</para></listitem>
- <listitem><para>Microsoft Windows Browser Protocol</para></listitem>
- <listitem><para>Microsoft Windows Lanman Remote API Protocol</para></listitem>
- <listitem><para>Microsoft Windows Logon Protocol</para></listitem>
- <listitem><para>Microsoft Workstation Service</para></listitem>
- <listitem><para>Mobile IP</para></listitem>
- <listitem><para>Modbus/TCP</para></listitem>
- <listitem><para>Mount Service</para></listitem>
- <listitem><para>MultiProtocol Label Switching Header</para></listitem>
- <listitem><para>Multicast Router DISCovery protocol</para></listitem>
- <listitem><para>Multicast Source Discovery Protocol</para></listitem>
- <listitem><para>NFSACL</para></listitem>
- <listitem><para>NFSAUTH</para></listitem>
- <listitem><para>NIS+</para></listitem>
- <listitem><para>NIS+ Callback</para></listitem>
- <listitem><para>NSPI</para></listitem>
- <listitem><para>NTLM Secure Service Provider</para></listitem>
- <listitem><para>Name Binding Protocol</para></listitem>
- <listitem><para>Name Management Protocol over IPX</para></listitem>
- <listitem><para>NetBIOS</para></listitem>
- <listitem><para>NetBIOS Datagram Service</para></listitem>
- <listitem><para>NetBIOS Name Service</para></listitem>
- <listitem><para>NetBIOS Session Service</para></listitem>
- <listitem><para>NetBIOS over IPX</para></listitem>
- <listitem><para>NetWare Core Protocol</para></listitem>
- <listitem><para>Network Data Management Protocol</para></listitem>
- <listitem><para>Network File System</para></listitem>
- <listitem><para>Network Lock Manager Protocol</para></listitem>
- <listitem><para>Network News Transfer Protocol</para></listitem>
- <listitem><para>Network Status Monitor CallBack Protocol</para></listitem>
- <listitem><para>Network Status Monitor Protocol</para></listitem>
- <listitem><para>Network Time Protocol</para></listitem>
- <listitem><para>Novell Distributed Print System</para></listitem>
- <listitem><para>Null/Loopback</para></listitem>
- <listitem><para>Open Shortest Path First</para></listitem>
- <listitem><para>OpenBSD Packet Filter log file</para></listitem>
- <listitem><para>PC NFS</para></listitem>
- <listitem><para>PPP Bandwidth Allocation Control Protocol</para></listitem>
- <listitem><para>PPP Bandwidth Allocation Protocol</para></listitem>
- <listitem><para>PPP CDP Control Protocol</para></listitem>
- <listitem><para>PPP Callback Control Protocol</para></listitem>
- <listitem><para>PPP Challenge Handshake Authentication Protocol</para></listitem>
- <listitem><para>PPP Compressed Datagram</para></listitem>
- <listitem><para>PPP Compression Control Protocol</para></listitem>
- <listitem><para>PPP IP Control Protocol</para></listitem>
- <listitem><para>PPP Link Control Protocol</para></listitem>
- <listitem><para>PPP MPLS Control Protocol</para></listitem>
- <listitem><para>PPP Multilink Protocol</para></listitem>
- <listitem><para>PPP Multiplexing</para></listitem>
- <listitem><para>PPP Password Authentication Protocol</para></listitem>
- <listitem><para>PPP VJ Compression</para></listitem>
- <listitem><para>PPP-over-Ethernet Discovery</para></listitem>
- <listitem><para>PPP-over-Ethernet Session</para></listitem>
- <listitem><para>PPPMux Control Protocol</para></listitem>
- <listitem><para>Point-to-Point Protocol</para></listitem>
- <listitem><para>Point-to-Point Tunnelling Protocol</para></listitem>
- <listitem><para>Portmap</para></listitem>
- <listitem><para>Post Office Protocol</para></listitem>
- <listitem><para>Pragmatic General Multicast</para></listitem>
- <listitem><para>Prism</para></listitem>
- <listitem><para>Privilege Server operations</para></listitem>
- <listitem><para>Protocol Independent Multicast</para></listitem>
- <listitem><para>Q.2931</para></listitem>
- <listitem><para>Q.931</para></listitem>
- <listitem><para>Quake II Network Protocol</para></listitem>
- <listitem><para>Quake III Arena Network Protocol</para></listitem>
- <listitem><para>Quake Network Protocol</para></listitem>
- <listitem><para>QuakeWorld Network Protocol</para></listitem>
- <listitem><para>Qualified Logical Link Control</para></listitem>
- <listitem><para>RFC 2250 MPEG1</para></listitem>
- <listitem><para>RIPng</para></listitem>
- <listitem><para>RPC Browser</para></listitem>
- <listitem><para>RSTAT</para></listitem>
- <listitem><para>RX Protocol</para></listitem>
- <listitem><para>Radio Access Network Application Part</para></listitem>
- <listitem><para>Radius Protocol</para></listitem>
- <listitem><para>Raw packet data</para></listitem>
- <listitem><para>Real Time Streaming Protocol</para></listitem>
- <listitem><para>Real-Time Transport Protocol</para></listitem>
- <listitem><para>Real-time Transport Control Protocol</para></listitem>
- <listitem><para>Registry Server Attributes Manipulation Interface</para></listitem>
- <listitem><para>Registry server administration operations.</para></listitem>
- <listitem><para>Remote Override interface</para></listitem>
- <listitem><para>Remote Procedure Call</para></listitem>
- <listitem><para>Remote Quota</para></listitem>
- <listitem><para>Remote Shell</para></listitem>
- <listitem><para>Remote Wall protocol</para></listitem>
- <listitem><para>Remote sec_login preauth interface.</para></listitem>
- <listitem><para>Resource ReserVation Protocol (RSVP)</para></listitem>
- <listitem><para>Rlogin Protocol</para></listitem>
- <listitem><para>Routing Information Protocol</para></listitem>
- <listitem><para>Routing Table Maintenance Protocol</para></listitem>
- <listitem><para>SADMIND</para></listitem>
- <listitem><para>SCSI</para></listitem>
- <listitem><para>SMB (Server Message Block Protocol)</para></listitem>
- <listitem><para>SMB MailSlot Protocol</para></listitem>
- <listitem><para>SMB Pipe Protocol</para></listitem>
- <listitem><para>SNA-over-Ethernet</para></listitem>
- <listitem><para>SNMP Multiplex Protocol</para></listitem>
- <listitem><para>SPNEGO-KRB5</para></listitem>
- <listitem><para>SPRAY</para></listitem>
- <listitem><para>SS7 SCCP-User Adaptation Layer</para></listitem>
- <listitem><para>SSCOP</para></listitem>
- <listitem><para>Secure Socket Layer</para></listitem>
- <listitem><para>Sequenced Packet eXchange</para></listitem>
- <listitem><para>Service Advertisement Protocol</para></listitem>
- <listitem><para>Service Location Protocol</para></listitem>
- <listitem><para>Session Announcement Protocol</para></listitem>
- <listitem><para>Session Description Protocol</para></listitem>
- <listitem><para>Session Initiation Protocol</para></listitem>
- <listitem><para>Short Frame</para></listitem>
- <listitem><para>Short Message Peer to Peer</para></listitem>
- <listitem><para>Signalling Connection Control Part</para></listitem>
- <listitem><para>Signalling Connection Control Part Management</para></listitem>
- <listitem><para>Simple Mail Transfer Protocol</para></listitem>
- <listitem><para>Simple Network Management Protocol</para></listitem>
- <listitem><para>Sinec H1 Protocol</para></listitem>
- <listitem><para>Skinny Client Control Protocol</para></listitem>
- <listitem><para>SliMP3 Communication Protocol</para></listitem>
- <listitem><para>Socks Protocol</para></listitem>
- <listitem><para>Spanning Tree Protocol</para></listitem>
- <listitem><para>Spnego</para></listitem>
- <listitem><para>Stream Control Transmission Protocol</para></listitem>
- <listitem><para>Syslog message</para></listitem>
- <listitem><para>Systems Network Architecture</para></listitem>
- <listitem><para>TACACS</para></listitem>
- <listitem><para>TACACS+</para></listitem>
- <listitem><para>TPKT</para></listitem>
- <listitem><para>Tabular Data Stream</para></listitem>
- <listitem><para>Telnet</para></listitem>
- <listitem><para>Time Protocol</para></listitem>
- <listitem><para>Time Service Provider Interfacer</para></listitem>
- <listitem><para>Time Synchronization Protocol</para></listitem>
- <listitem><para>Token-Ring</para></listitem>
- <listitem><para>Token-Ring Media Access Control</para></listitem>
- <listitem><para>Transmission Control Protocol</para></listitem>
- <listitem><para>Transparent Network Substrate Protocol</para></listitem>
- <listitem><para>Trivial File Transfer Protocol</para></listitem>
- <listitem><para>Universal Computer Protocol</para></listitem>
- <listitem><para>Unreassembled Fragmented Packet</para></listitem>
- <listitem><para>User Datagram Protocol</para></listitem>
- <listitem><para>Virtual Router Redundancy Protocol</para></listitem>
- <listitem><para>Virtual Trunking Protocol</para></listitem>
- <listitem><para>Web Cache Coordination Protocol</para></listitem>
- <listitem><para>Wellfleet Compression</para></listitem>
- <listitem><para>Who</para></listitem>
- <listitem><para>Windows 2000 DNS</para></listitem>
- <listitem><para>Wireless Session Protocol</para></listitem>
- <listitem><para>Wireless Transaction Protocol</para></listitem>
- <listitem><para>Wireless Transport Layer Security</para></listitem>
- <listitem><para>X Display Manager Control Protocol</para></listitem>
- <listitem><para>X.25</para></listitem>
- <listitem><para>X.25 over TCP</para></listitem>
- <listitem><para>X11</para></listitem>
- <listitem><para>Xyplex</para></listitem>
- <listitem><para>Yahoo Messenger Protocol</para></listitem>
- <listitem><para>Yellow Pages Bind</para></listitem>
- <listitem><para>Yellow Pages Passwd</para></listitem>
- <listitem><para>Yellow Pages Service</para></listitem>
- <listitem><para>Yellow Pages Transfer</para></listitem>
- <listitem><para>Zebra Protocol</para></listitem>
- <listitem><para>Zone Information Protocol</para></listitem>
- <listitem><para>iSCSI</para></listitem>
-</itemizedlist>
+<!-- $Id$ --> + +<itemizedlist id="EtherealListOfProtos"> + <listitem><para>802.1q Virtual LAN</para></listitem> + <listitem><para>802.1x Authentication</para></listitem> + <listitem><para>AFS (4.0) Replication Server call declarations</para></listitem> + <listitem><para>AOL Instant Messenger</para></listitem> + <listitem><para>ATM</para></listitem> + <listitem><para>ATM LAN Emulation</para></listitem> + <listitem><para>Ad hoc On-demand Distance Vector Routing Protocol</para></listitem> + <listitem><para>Ad hoc On-demand Distance Vector Routing Protocol v6</para></listitem> + <listitem><para>Address Resolution Protocol</para></listitem> + <listitem><para>Aggregate Server Access Protocol</para></listitem> + <listitem><para>Andrew File System (AFS)</para></listitem> + <listitem><para>Apache JServ Protocol v1.3</para></listitem> + <listitem><para>AppleTalk Filing Protocol</para></listitem> + <listitem><para>AppleTalk Session Protocol</para></listitem> + <listitem><para>AppleTalk Transaction Protocol packet</para></listitem> + <listitem><para>Appletalk Address Resolution Protocol</para></listitem> + <listitem><para>Async data over ISDN (V.120)</para></listitem> + <listitem><para>Authentication Header</para></listitem> + <listitem><para>BACnet Virtual Link Control</para></listitem> + <listitem><para>Banyan Vines</para></listitem> + <listitem><para>Banyan Vines Fragmentation Protocol</para></listitem> + <listitem><para>Banyan Vines SPP</para></listitem> + <listitem><para>Blocks Extensible Exchange Protocol</para></listitem> + <listitem><para>Boot Parameters</para></listitem> + <listitem><para>Bootstrap Protocol</para></listitem> + <listitem><para>Border Gateway Protocol</para></listitem> + <listitem><para>Building Automation and Control Network APDU</para></listitem> + <listitem><para>Building Automation and Control Network NPDU</para></listitem> + <listitem><para>CDS Clerk Server Calls</para></listitem> + <listitem><para>Check Point High Availability Protocol</para></listitem> + <listitem><para>Checkpoint FW-1</para></listitem> + <listitem><para>Cisco Auto-RP</para></listitem> + <listitem><para>Cisco Discovery Protocol</para></listitem> + <listitem><para>Cisco Group Management Protocol</para></listitem> + <listitem><para>Cisco HDLC</para></listitem> + <listitem><para>Cisco Hot Standby Router Protocol</para></listitem> + <listitem><para>Cisco ISL</para></listitem> + <listitem><para>Cisco Interior Gateway Routing Protocol</para></listitem> + <listitem><para>Cisco NetFlow</para></listitem> + <listitem><para>Cisco SLARP</para></listitem> + <listitem><para>CoSine IPNOS L2 debug output</para></listitem> + <listitem><para>Common Open Policy Service</para></listitem> + <listitem><para>Common Unix Printing System (CUPS) Browsing Protocol</para></listitem> + <listitem><para>DCE DFS Calls</para></listitem> + <listitem><para>DCE Name Service</para></listitem> + <listitem><para>DCE RPC</para></listitem> + <listitem><para>DCE Security ID Mapper</para></listitem> + <listitem><para>DCE/RPC BOS Server</para></listitem> + <listitem><para>DCE/RPC CDS Solicitation</para></listitem> + <listitem><para>DCE/RPC Conversation Manager</para></listitem> + <listitem><para>DCE/RPC Endpoint Mapper</para></listitem> + <listitem><para>DCE/RPC FLDB</para></listitem> + <listitem><para>DCE/RPC FLDB UBIK TRANSFER</para></listitem> + <listitem><para>DCE/RPC Kerberos V</para></listitem> + <listitem><para>DCE/RPC RS_ACCT</para></listitem> + <listitem><para>DCE/RPC RS_MISC</para></listitem> + <listitem><para>DCE/RPC RS_UNIX</para></listitem> + <listitem><para>DCE/RPC Remote Management</para></listitem> + <listitem><para>DCE/RPC Repserver Calls</para></listitem> + <listitem><para>DCE/RPC TokenServer Calls</para></listitem> + <listitem><para>DCOM OXID Resolver</para></listitem> + <listitem><para>DCOM Remote Activation</para></listitem> + <listitem><para>DEC Spanning Tree Protocol</para></listitem> + <listitem><para>DHCPv6</para></listitem> + <listitem><para>DNS Control Program Server</para></listitem> + <listitem><para>Data</para></listitem> + <listitem><para>Data Link SWitching</para></listitem> + <listitem><para>Data Stream Interface</para></listitem> + <listitem><para>Datagram Delivery Protocol</para></listitem> + <listitem><para>Diameter Protocol</para></listitem> + <listitem><para>Distance Vector Multicast Routing Protocol</para></listitem> + <listitem><para>Distributed Checksum Clearinghouse Prototocl</para></listitem> + <listitem><para>Domain Name Service</para></listitem> + <listitem><para>Dummy Protocol</para></listitem> + <listitem><para>Dynamic DNS Tools Protocol</para></listitem> + <listitem><para>Encapsulating Security Payload</para></listitem> + <listitem><para>Enhanced Interior Gateway Routing Protocol</para></listitem> + <listitem><para>Ethernet</para></listitem> + <listitem><para>Extensible Authentication Protocol</para></listitem> + <listitem><para>FTP Data</para></listitem> + <listitem><para>FTServer Operations</para></listitem> + <listitem><para>Fiber Distributed Data Interface</para></listitem> + <listitem><para>File Transfer Protocol (FTP)</para></listitem> + <listitem><para>Financial Information eXchange Protocol</para></listitem> + <listitem><para>Frame</para></listitem> + <listitem><para>Frame Relay</para></listitem> + <listitem><para>GARP Multicast Registration Protocol</para></listitem> + <listitem><para>GARP VLAN Registration Protocol</para></listitem> + <listitem><para>GPRS Tunneling Protocol</para></listitem> + <listitem><para>GPRS Tunnelling Protocol v0</para></listitem> + <listitem><para>GPRS Tunnelling Protocol v1</para></listitem> + <listitem><para>General Inter-ORB Protocol</para></listitem> + <listitem><para>Generic Routing Encapsulation</para></listitem> + <listitem><para>Generic Security Service Application Program Interface</para></listitem> + <listitem><para>Gnutella Protocol</para></listitem> + <listitem><para>Hummingbird NFS Daemon</para></listitem> + <listitem><para>Hypertext Transfer Protocol</para></listitem> + <listitem><para>ICQ Protocol</para></listitem> + <listitem><para>IEEE 802.11 wireless LAN</para></listitem> + <listitem><para>IEEE 802.11 wireless LAN management frame</para></listitem> + <listitem><para>ILMI</para></listitem> + <listitem><para>IP Payload Compression</para></listitem> + <listitem><para>IPX Message</para></listitem> + <listitem><para>IPX Routing Information Protocol</para></listitem> + <listitem><para>ISDN Q.921-User Adaptation Layer</para></listitem> + <listitem><para>ISDN User Part</para></listitem> + <listitem><para>ISO 10589 ISIS InTRA Domain Routeing Information Exchange Protocol</para></listitem> + <listitem><para>ISO 8073 COTP Connection-Oriented Transport Protocol</para></listitem> + <listitem><para>ISO 8473 CLNP ConnectionLess Network Protocol</para></listitem> + <listitem><para>ISO 8602 CLTP ConnectionLess Transport Protocol</para></listitem> + <listitem><para>ISO 9542 ESIS Routeing Information Exchange Protocol</para></listitem> + <listitem><para>ITU-T Recommendation H.261</para></listitem> + <listitem><para>Inter-Access-Point Protocol</para></listitem> + <listitem><para>Interbase</para></listitem> + <listitem><para>Internet Cache Protocol</para></listitem> + <listitem><para>Internet Content Adaptation Protocol</para></listitem> + <listitem><para>Internet Control Message Protocol</para></listitem> + <listitem><para>Internet Control Message Protocol v6</para></listitem> + <listitem><para>Internet Group Management Protocol</para></listitem> + <listitem><para>Internet Message Access Protocol</para></listitem> + <listitem><para>Internet Printing Protocol</para></listitem> + <listitem><para>Internet Protocol</para></listitem> + <listitem><para>Internet Protocol Version 6</para></listitem> + <listitem><para>Internet Relay Chat</para></listitem> + <listitem><para>Internet Security Association and Key Management Protocol</para></listitem> + <listitem><para>Internetwork Packet eXchange</para></listitem> + <listitem><para>Java RMI</para></listitem> + <listitem><para>Java Serialization</para></listitem> + <listitem><para>Kerberos</para></listitem> + <listitem><para>Kernel Lock Manager</para></listitem> + <listitem><para>Label Distribution Protocol</para></listitem> + <listitem><para>Layer 2 Tunneling Protocol</para></listitem> + <listitem><para>Lightweight Directory Access Protocol</para></listitem> + <listitem><para>Line Printer Daemon Protocol</para></listitem> + <listitem><para>Link Access Procedure Balanced (LAPB)</para></listitem> + <listitem><para>Link Access Procedure Balanced Ethernet (LAPBETHER)</para></listitem> + <listitem><para>Link Access Procedure, Channel D (LAPD)</para></listitem> + <listitem><para>Link Aggregation Control Protocol</para></listitem> + <listitem><para>Link Management Protocol (LMP)</para></listitem> + <listitem><para>Linux cooked-mode capture</para></listitem> + <listitem><para>Local Management Interface</para></listitem> + <listitem><para>LocalTalk Link Access Protocol</para></listitem> + <listitem><para>Logical-Link Control</para></listitem> + <listitem><para>Lucent/Ascend debug output</para></listitem> + <listitem><para>MMS Message Encapsulation</para></listitem> + <listitem><para>MS Proxy Protocol</para></listitem> + <listitem><para>MSNIP: Multicast Source Notification of Interest Protocol</para></listitem> + <listitem><para>MTP 2 Transparent Proxy</para></listitem> + <listitem><para>MTP 2 User Adaptation Layer</para></listitem> + <listitem><para>MTP 3 User Adaptation Layer</para></listitem> + <listitem><para>MTP2 Peer Adaptation Layer</para></listitem> + <listitem><para>Malformed Packet</para></listitem> + <listitem><para>Message Transfer Part Level 2</para></listitem> + <listitem><para>Message Transfer Part Level 3</para></listitem> + <listitem><para>Microsoft Distributed File System</para></listitem> + <listitem><para>Microsoft Exchange MAPI</para></listitem> + <listitem><para>Microsoft Local Security Architecture</para></listitem> + <listitem><para>Microsoft Network Logon</para></listitem> + <listitem><para>Microsoft Registry</para></listitem> + <listitem><para>Microsoft Security Account Manager</para></listitem> + <listitem><para>Microsoft Server Service</para></listitem> + <listitem><para>Microsoft Spool Subsystem</para></listitem> + <listitem><para>Microsoft Telephony API Service</para></listitem> + <listitem><para>Microsoft Windows Browser Protocol</para></listitem> + <listitem><para>Microsoft Windows Lanman Remote API Protocol</para></listitem> + <listitem><para>Microsoft Windows Logon Protocol</para></listitem> + <listitem><para>Microsoft Workstation Service</para></listitem> + <listitem><para>Mobile IP</para></listitem> + <listitem><para>Modbus/TCP</para></listitem> + <listitem><para>Mount Service</para></listitem> + <listitem><para>MultiProtocol Label Switching Header</para></listitem> + <listitem><para>Multicast Router DISCovery protocol</para></listitem> + <listitem><para>Multicast Source Discovery Protocol</para></listitem> + <listitem><para>NFSACL</para></listitem> + <listitem><para>NFSAUTH</para></listitem> + <listitem><para>NIS+</para></listitem> + <listitem><para>NIS+ Callback</para></listitem> + <listitem><para>NSPI</para></listitem> + <listitem><para>NTLM Secure Service Provider</para></listitem> + <listitem><para>Name Binding Protocol</para></listitem> + <listitem><para>Name Management Protocol over IPX</para></listitem> + <listitem><para>NetBIOS</para></listitem> + <listitem><para>NetBIOS Datagram Service</para></listitem> + <listitem><para>NetBIOS Name Service</para></listitem> + <listitem><para>NetBIOS Session Service</para></listitem> + <listitem><para>NetBIOS over IPX</para></listitem> + <listitem><para>NetWare Core Protocol</para></listitem> + <listitem><para>Network Data Management Protocol</para></listitem> + <listitem><para>Network File System</para></listitem> + <listitem><para>Network Lock Manager Protocol</para></listitem> + <listitem><para>Network News Transfer Protocol</para></listitem> + <listitem><para>Network Status Monitor CallBack Protocol</para></listitem> + <listitem><para>Network Status Monitor Protocol</para></listitem> + <listitem><para>Network Time Protocol</para></listitem> + <listitem><para>Novell Distributed Print System</para></listitem> + <listitem><para>Null/Loopback</para></listitem> + <listitem><para>Open Shortest Path First</para></listitem> + <listitem><para>OpenBSD Packet Filter log file</para></listitem> + <listitem><para>PC NFS</para></listitem> + <listitem><para>PPP Bandwidth Allocation Control Protocol</para></listitem> + <listitem><para>PPP Bandwidth Allocation Protocol</para></listitem> + <listitem><para>PPP CDP Control Protocol</para></listitem> + <listitem><para>PPP Callback Control Protocol</para></listitem> + <listitem><para>PPP Challenge Handshake Authentication Protocol</para></listitem> + <listitem><para>PPP Compressed Datagram</para></listitem> + <listitem><para>PPP Compression Control Protocol</para></listitem> + <listitem><para>PPP IP Control Protocol</para></listitem> + <listitem><para>PPP Link Control Protocol</para></listitem> + <listitem><para>PPP MPLS Control Protocol</para></listitem> + <listitem><para>PPP Multilink Protocol</para></listitem> + <listitem><para>PPP Multiplexing</para></listitem> + <listitem><para>PPP Password Authentication Protocol</para></listitem> + <listitem><para>PPP VJ Compression</para></listitem> + <listitem><para>PPP-over-Ethernet Discovery</para></listitem> + <listitem><para>PPP-over-Ethernet Session</para></listitem> + <listitem><para>PPPMux Control Protocol</para></listitem> + <listitem><para>Point-to-Point Protocol</para></listitem> + <listitem><para>Point-to-Point Tunnelling Protocol</para></listitem> + <listitem><para>Portmap</para></listitem> + <listitem><para>Post Office Protocol</para></listitem> + <listitem><para>Pragmatic General Multicast</para></listitem> + <listitem><para>Prism</para></listitem> + <listitem><para>Privilege Server operations</para></listitem> + <listitem><para>Protocol Independent Multicast</para></listitem> + <listitem><para>Q.2931</para></listitem> + <listitem><para>Q.931</para></listitem> + <listitem><para>Quake II Network Protocol</para></listitem> + <listitem><para>Quake III Arena Network Protocol</para></listitem> + <listitem><para>Quake Network Protocol</para></listitem> + <listitem><para>QuakeWorld Network Protocol</para></listitem> + <listitem><para>Qualified Logical Link Control</para></listitem> + <listitem><para>RFC 2250 MPEG1</para></listitem> + <listitem><para>RIPng</para></listitem> + <listitem><para>RPC Browser</para></listitem> + <listitem><para>RSTAT</para></listitem> + <listitem><para>RX Protocol</para></listitem> + <listitem><para>Radio Access Network Application Part</para></listitem> + <listitem><para>Radius Protocol</para></listitem> + <listitem><para>Raw packet data</para></listitem> + <listitem><para>Real Time Streaming Protocol</para></listitem> + <listitem><para>Real-Time Transport Protocol</para></listitem> + <listitem><para>Real-time Transport Control Protocol</para></listitem> + <listitem><para>Registry Server Attributes Manipulation Interface</para></listitem> + <listitem><para>Registry server administration operations.</para></listitem> + <listitem><para>Remote Override interface</para></listitem> + <listitem><para>Remote Procedure Call</para></listitem> + <listitem><para>Remote Quota</para></listitem> + <listitem><para>Remote Shell</para></listitem> + <listitem><para>Remote Wall protocol</para></listitem> + <listitem><para>Remote sec_login preauth interface.</para></listitem> + <listitem><para>Resource ReserVation Protocol (RSVP)</para></listitem> + <listitem><para>Rlogin Protocol</para></listitem> + <listitem><para>Routing Information Protocol</para></listitem> + <listitem><para>Routing Table Maintenance Protocol</para></listitem> + <listitem><para>SADMIND</para></listitem> + <listitem><para>SCSI</para></listitem> + <listitem><para>SMB (Server Message Block Protocol)</para></listitem> + <listitem><para>SMB MailSlot Protocol</para></listitem> + <listitem><para>SMB Pipe Protocol</para></listitem> + <listitem><para>SNA-over-Ethernet</para></listitem> + <listitem><para>SNMP Multiplex Protocol</para></listitem> + <listitem><para>SPNEGO-KRB5</para></listitem> + <listitem><para>SPRAY</para></listitem> + <listitem><para>SS7 SCCP-User Adaptation Layer</para></listitem> + <listitem><para>SSCOP</para></listitem> + <listitem><para>Secure Socket Layer</para></listitem> + <listitem><para>Sequenced Packet eXchange</para></listitem> + <listitem><para>Service Advertisement Protocol</para></listitem> + <listitem><para>Service Location Protocol</para></listitem> + <listitem><para>Session Announcement Protocol</para></listitem> + <listitem><para>Session Description Protocol</para></listitem> + <listitem><para>Session Initiation Protocol</para></listitem> + <listitem><para>Short Frame</para></listitem> + <listitem><para>Short Message Peer to Peer</para></listitem> + <listitem><para>Signalling Connection Control Part</para></listitem> + <listitem><para>Signalling Connection Control Part Management</para></listitem> + <listitem><para>Simple Mail Transfer Protocol</para></listitem> + <listitem><para>Simple Network Management Protocol</para></listitem> + <listitem><para>Sinec H1 Protocol</para></listitem> + <listitem><para>Skinny Client Control Protocol</para></listitem> + <listitem><para>SliMP3 Communication Protocol</para></listitem> + <listitem><para>Socks Protocol</para></listitem> + <listitem><para>Spanning Tree Protocol</para></listitem> + <listitem><para>Spnego</para></listitem> + <listitem><para>Stream Control Transmission Protocol</para></listitem> + <listitem><para>Syslog message</para></listitem> + <listitem><para>Systems Network Architecture</para></listitem> + <listitem><para>TACACS</para></listitem> + <listitem><para>TACACS+</para></listitem> + <listitem><para>TPKT</para></listitem> + <listitem><para>Tabular Data Stream</para></listitem> + <listitem><para>Telnet</para></listitem> + <listitem><para>Time Protocol</para></listitem> + <listitem><para>Time Service Provider Interfacer</para></listitem> + <listitem><para>Time Synchronization Protocol</para></listitem> + <listitem><para>Token-Ring</para></listitem> + <listitem><para>Token-Ring Media Access Control</para></listitem> + <listitem><para>Transmission Control Protocol</para></listitem> + <listitem><para>Transparent Network Substrate Protocol</para></listitem> + <listitem><para>Trivial File Transfer Protocol</para></listitem> + <listitem><para>Universal Computer Protocol</para></listitem> + <listitem><para>Unreassembled Fragmented Packet</para></listitem> + <listitem><para>User Datagram Protocol</para></listitem> + <listitem><para>Virtual Router Redundancy Protocol</para></listitem> + <listitem><para>Virtual Trunking Protocol</para></listitem> + <listitem><para>Web Cache Coordination Protocol</para></listitem> + <listitem><para>Wellfleet Compression</para></listitem> + <listitem><para>Who</para></listitem> + <listitem><para>Windows 2000 DNS</para></listitem> + <listitem><para>Wireless Session Protocol</para></listitem> + <listitem><para>Wireless Transaction Protocol</para></listitem> + <listitem><para>Wireless Transport Layer Security</para></listitem> + <listitem><para>X Display Manager Control Protocol</para></listitem> + <listitem><para>X.25</para></listitem> + <listitem><para>X.25 over TCP</para></listitem> + <listitem><para>X11</para></listitem> + <listitem><para>Xyplex</para></listitem> + <listitem><para>Yahoo Messenger Protocol</para></listitem> + <listitem><para>Yellow Pages Bind</para></listitem> + <listitem><para>Yellow Pages Passwd</para></listitem> + <listitem><para>Yellow Pages Service</para></listitem> + <listitem><para>Yellow Pages Transfer</para></listitem> + <listitem><para>Zebra Protocol</para></listitem> + <listitem><para>Zone Information Protocol</para></listitem> + <listitem><para>iSCSI</para></listitem> +</itemizedlist> diff --git a/docbook/ug-src/EUG_app_files.xml b/docbook/ug-src/EUG_app_files.xml index 485b2d0942..5e70ab5bbe 100644 --- a/docbook/ug-src/EUG_app_files.xml +++ b/docbook/ug-src/EUG_app_files.xml @@ -1,290 +1,292 @@ -<!-- EUG Appendix Files -->
-<appendix id="AppFiles">
- <title>Configuration Files and Folders</title>
- <para>
- Ethereal uses a number of files while it is running. Some of these
- reside in the personal configuration folder and are used to maintain
- information between runs of Ethereal, while some of them are maintained
- in system areas.
- </para>
- <para>
- XXX - Add info about "temporary capture file" folders.
- </para>
- <tip><title>Tip</title>
- <para>A list of the folders Ethereal actually uses can be found under the
- "Folders" tab in the "About" dialog box.
- </para>
- </tip>
- <para>
- The content format of the configuration files is the same on all platforms.
- However, to match the different policies for unix and windows platforms,
- different folders for these files are used.
- </para>
- <table id="AppFilesTabFolders" frame="none"><title>Configuration files overview</title>
- <tgroup cols="4">
- <colspec colnum="1" colwidth="72pt"/>
- <colspec colnum="2" colwidth="80pt"/>
- <colspec colnum="3" colwidth="80pt"/>
- <thead>
- <row>
- <entry>File</entry>
- <entry>Description</entry>
- <entry>Unix folders</entry>
- <entry>Windows folders</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><command>preferences</command></entry>
- <entry>Settings from the Preferences dialog box.</entry>
- <entry>$HOME/.ethereal/preferences</entry>
- <entry>%ETHEREAL%\preferences, %APPDATA%\Ethereal\preferences</entry>
- </row>
- <row>
- <entry><command>recent</command></entry>
- <entry>Recent GUI settings (e.g. recent files lists).</entry>
- <entry>$HOME/.ethereal/recent</entry>
- <entry>%APPDATA%\Ethereal\recent</entry>
- </row>
- <row>
- <entry><command>cfilters</command></entry>
- <entry>Capture filters.</entry>
- <entry>$HOME/.ethereal/cfilters</entry>
- <entry>%ETHEREAL%\cfilters, %APPDATA%\Ethereal\cfilters</entry>
- </row>
- <row>
- <entry><command>dfilters</command></entry>
- <entry>Display filters.</entry>
- <entry>$HOME/.ethereal/dfilters</entry>
- <entry>%ETHEREAL%\dfilters, %APPDATA%\Ethereal\dfilters</entry>
- </row>
- <row>
- <entry><command>colorfilters</command></entry>
- <entry>Coloring rules.</entry>
- <entry>$HOME/.ethereal/colorfilters</entry>
- <entry>%ETHEREAL%\colorfilters, %APPDATA%\Ethereal\colorfilters</entry>
- </row>
- <row>
- <entry><command>disabled_protos</command></entry>
- <entry>Disabled protocols.</entry>
- <entry>$HOME/.ethereal/disabled_protos</entry>
- <entry>%APPDATA%\Ethereal\disabled_protos</entry>
- </row>
- <row>
- <entry><command>ethers</command></entry>
- <entry>Ethernet name resolution.</entry>
- <entry>/etc/ethers, $HOME/.ethereal/ethers</entry>
- <entry>%ETHEREAL%\ethers, %APPDATA%\Ethereal\ethers</entry>
- </row>
- <row>
- <entry><command>manuf</command></entry>
- <entry>Ethernet name resolution.</entry>
- <entry>/usr/local/etc/manuf</entry>
- <entry>%ETHEREAL%\manuf</entry>
- </row>
- <row>
- <entry><command>ipxnets</command></entry>
- <entry>IPX name resolution.</entry>
- <entry>$HOME/.ethereal/ipxnets</entry>
- <entry>%ETHEREAL%\ipxnets</entry>
- </row>
- <row>
- <entry><command>plugins</command></entry>
- <entry>Plugin directories.</entry>
- <entry>/usr/share/ethereal/plugins,
- /usr/local/share/ethereals/plugins,
- $HOME/.ethereal/plugins
- </entry>
- <entry>%ETHEREAL%\plugins\<version>,
- %APPDATA%\Ethereal\plugins</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <note><title>Windows folders</title>
- <para>
- %APPDATA% points to the personal configuration folder, typically
- "C:\Documents and Settings\<username>\Application Data",
- %ETHEREAL% points to the Ethereal program folder, typically
- "C:\Program Files\Ethereal"
- </para>
- </note>
- <para>
- <variablelist>
- <varlistentry>
- <term><command>preferences</command></term>
- <listitem>
- <para>
- This file contains your Ethereal preferences,
- including defaults for capturing and displaying packets.
- It is a simple text file containing statements of the form:
- <programlisting>
-variable: value
- </programlisting>
- The settings from this file are
- read in at program start and written to disk when you press the
- Save button in the "Preferences" dialog box.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><command>recent</command></term>
- <listitem>
- <para>
- This file contains various GUI related settings like the main window
- position and size, the recent files list and such.
- It is a simple text file containing statements of the form:
- <programlisting>
-variable: value
- </programlisting>
- It is read at program start and written at program exit.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>cfilters</command></term>
- <listitem>
- <para>
- This file contains all the capture filters that you have defined
- and saved. It consists of one or more lines, where each
- line has the following format:
- <programlisting>
-"<filter name>" <filter string>
- </programlisting>
- The settings from this file are read in at program start and written
- to disk when you press the Save button in the "Capture Filters" dialog
- box.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>dfilters</command></term>
- <listitem>
- <para>
- This file contains all the display filters that you have defined
- and saved. It consists of one or more lines, where each
- line has the following format:
- <programlisting>
-"<filter name>" <filter string>
- </programlisting>
- The settings from this file are read in at program start and written
- to disk when you press the Save button in the "Display Filters" dialog
- box.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><command>colorfilters</command></term>
- <listitem>
- <para>
- This file contains all the color filters that you have
- defined and saved. It consists of one or more lines,
- where each line has the following format:
- <programlisting>
-@<filter name>@<filter string>
-@[<bg RGB(16-bit)>][<fg RGB(16-bit)>]
- </programlisting>
- </para>
- <para>
- The settings from this file are read in at program start and written
- to disk when you press the Save button in the "Coloring Rules" dialog
- box.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><command>disabled_protos</command></term>
- <listitem>
- <para>
- Each line in this file specifies a disabled protocol name. The
- following are some examples:
- <programlisting>
-tcp
-udp
- </programlisting>
- </para>
- <para>
- The settings from this file are read in at program start and written
- to disk when you press the Save button in the "Enabled Protocols"
- dialog box.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <command>ethers</command>
- </term>
- <listitem>
- <para>
- When Ethereal is trying to translate Ethernet hardware
- addresses to names, it consults the files listed in
- <xref linkend="AppFilesTabFolders"/>.
- If an address is not found in /etc/ethers,
- Ethereal looks in $HOME/.ethereal/ethers
- </para>
- <para>
- Each line in these files consists of one hardware address and
- name separated by whitespace. The digits of hardware
- addressses are separated by colons (:), dashes (-) or
- periods(.). The following are some examples:
- <programlisting>
-ff-ff-ff-ff-ff-ff Broadcast
-c0-00-ff-ff-ff-ff TR_broadcast
-00.2b.08.93.4b.a1 Freds_machine
- </programlisting>
- The settings from this file are read in at program start and never
- written by Ethereal.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><command>manuf</command></term>
- <listitem>
- <para>
- Ethereal uses the files listed in <xref linkend="AppFilesTabFolders"/>
- to translate the first three bytes of an Ethernet address into a
- manufacturers name. This file has the same format as the ethers
- file, except addresses are three bytes long.
- </para>
- <para>
- The settings from this file are read in at program start and never
- written by Ethereal.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><command>ipxnets</command></term>
- <listitem>
- <para>
- Ethereal uses the files listed in <xref linkend="AppFilesTabFolders"/>
- to translate IPX network numbers into names.
- </para>
- <para>
- An example is:
- <programlisting>
-C0.A8.2C.00 HR
-c0-a8-1c-00 CEO
-00:00:BE:EF IT_Server1
-110f FileServer3
- </programlisting>
- </para>
- <para>
- The settings from this file are read in at program start and never
- written by Ethereal.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><command>plugins</command></term>
- <listitem>
- <para>
- Ethereal searches for plugins in the directories listed in
- <xref linkend="AppFilesTabFolders"/>.
- They are searched in the order listed.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
-<!-- </section> -->
-
-</appendix>
-<!-- End of EUG Appendix Files -->
+<!-- EUG Appendix Files --> +<!-- $Id$ --> + +<appendix id="AppFiles"> + <title>Configuration Files and Folders</title> + <para> + Ethereal uses a number of files while it is running. Some of these + reside in the personal configuration folder and are used to maintain + information between runs of Ethereal, while some of them are maintained + in system areas. + </para> + <para> + XXX - Add info about "temporary capture file" folders. + </para> + <tip><title>Tip</title> + <para>A list of the folders Ethereal actually uses can be found under the + "Folders" tab in the "About" dialog box. + </para> + </tip> + <para> + The content format of the configuration files is the same on all platforms. + However, to match the different policies for unix and windows platforms, + different folders for these files are used. + </para> + <table id="AppFilesTabFolders" frame="none"><title>Configuration files overview</title> + <tgroup cols="4"> + <colspec colnum="1" colwidth="72pt"/> + <colspec colnum="2" colwidth="80pt"/> + <colspec colnum="3" colwidth="80pt"/> + <thead> + <row> + <entry>File</entry> + <entry>Description</entry> + <entry>Unix folders</entry> + <entry>Windows folders</entry> + </row> + </thead> + <tbody> + <row> + <entry><command>preferences</command></entry> + <entry>Settings from the Preferences dialog box.</entry> + <entry>$HOME/.ethereal/preferences</entry> + <entry>%ETHEREAL%\preferences, %APPDATA%\Ethereal\preferences</entry> + </row> + <row> + <entry><command>recent</command></entry> + <entry>Recent GUI settings (e.g. recent files lists).</entry> + <entry>$HOME/.ethereal/recent</entry> + <entry>%APPDATA%\Ethereal\recent</entry> + </row> + <row> + <entry><command>cfilters</command></entry> + <entry>Capture filters.</entry> + <entry>$HOME/.ethereal/cfilters</entry> + <entry>%ETHEREAL%\cfilters, %APPDATA%\Ethereal\cfilters</entry> + </row> + <row> + <entry><command>dfilters</command></entry> + <entry>Display filters.</entry> + <entry>$HOME/.ethereal/dfilters</entry> + <entry>%ETHEREAL%\dfilters, %APPDATA%\Ethereal\dfilters</entry> + </row> + <row> + <entry><command>colorfilters</command></entry> + <entry>Coloring rules.</entry> + <entry>$HOME/.ethereal/colorfilters</entry> + <entry>%ETHEREAL%\colorfilters, %APPDATA%\Ethereal\colorfilters</entry> + </row> + <row> + <entry><command>disabled_protos</command></entry> + <entry>Disabled protocols.</entry> + <entry>$HOME/.ethereal/disabled_protos</entry> + <entry>%APPDATA%\Ethereal\disabled_protos</entry> + </row> + <row> + <entry><command>ethers</command></entry> + <entry>Ethernet name resolution.</entry> + <entry>/etc/ethers, $HOME/.ethereal/ethers</entry> + <entry>%ETHEREAL%\ethers, %APPDATA%\Ethereal\ethers</entry> + </row> + <row> + <entry><command>manuf</command></entry> + <entry>Ethernet name resolution.</entry> + <entry>/usr/local/etc/manuf</entry> + <entry>%ETHEREAL%\manuf</entry> + </row> + <row> + <entry><command>ipxnets</command></entry> + <entry>IPX name resolution.</entry> + <entry>$HOME/.ethereal/ipxnets</entry> + <entry>%ETHEREAL%\ipxnets</entry> + </row> + <row> + <entry><command>plugins</command></entry> + <entry>Plugin directories.</entry> + <entry>/usr/share/ethereal/plugins, + /usr/local/share/ethereals/plugins, + $HOME/.ethereal/plugins + </entry> + <entry>%ETHEREAL%\plugins\<version>, + %APPDATA%\Ethereal\plugins</entry> + </row> + </tbody> + </tgroup> + </table> + <note><title>Windows folders</title> + <para> + %APPDATA% points to the personal configuration folder, typically + "C:\Documents and Settings\<username>\Application Data", + %ETHEREAL% points to the Ethereal program folder, typically + "C:\Program Files\Ethereal" + </para> + </note> + <para> + <variablelist> + <varlistentry> + <term><command>preferences</command></term> + <listitem> + <para> + This file contains your Ethereal preferences, + including defaults for capturing and displaying packets. + It is a simple text file containing statements of the form: + <programlisting> +variable: value + </programlisting> + The settings from this file are + read in at program start and written to disk when you press the + Save button in the "Preferences" dialog box. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command>recent</command></term> + <listitem> + <para> + This file contains various GUI related settings like the main window + position and size, the recent files list and such. + It is a simple text file containing statements of the form: + <programlisting> +variable: value + </programlisting> + It is read at program start and written at program exit. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>cfilters</command></term> + <listitem> + <para> + This file contains all the capture filters that you have defined + and saved. It consists of one or more lines, where each + line has the following format: + <programlisting> +"<filter name>" <filter string> + </programlisting> + The settings from this file are read in at program start and written + to disk when you press the Save button in the "Capture Filters" dialog + box. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>dfilters</command></term> + <listitem> + <para> + This file contains all the display filters that you have defined + and saved. It consists of one or more lines, where each + line has the following format: + <programlisting> +"<filter name>" <filter string> + </programlisting> + The settings from this file are read in at program start and written + to disk when you press the Save button in the "Display Filters" dialog + box. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command>colorfilters</command></term> + <listitem> + <para> + This file contains all the color filters that you have + defined and saved. It consists of one or more lines, + where each line has the following format: + <programlisting> +@<filter name>@<filter string> +@[<bg RGB(16-bit)>][<fg RGB(16-bit)>] + </programlisting> + </para> + <para> + The settings from this file are read in at program start and written + to disk when you press the Save button in the "Coloring Rules" dialog + box. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command>disabled_protos</command></term> + <listitem> + <para> + Each line in this file specifies a disabled protocol name. The + following are some examples: + <programlisting> +tcp +udp + </programlisting> + </para> + <para> + The settings from this file are read in at program start and written + to disk when you press the Save button in the "Enabled Protocols" + dialog box. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <command>ethers</command> + </term> + <listitem> + <para> + When Ethereal is trying to translate Ethernet hardware + addresses to names, it consults the files listed in + <xref linkend="AppFilesTabFolders"/>. + If an address is not found in /etc/ethers, + Ethereal looks in $HOME/.ethereal/ethers + </para> + <para> + Each line in these files consists of one hardware address and + name separated by whitespace. The digits of hardware + addressses are separated by colons (:), dashes (-) or + periods(.). The following are some examples: + <programlisting> +ff-ff-ff-ff-ff-ff Broadcast +c0-00-ff-ff-ff-ff TR_broadcast +00.2b.08.93.4b.a1 Freds_machine + </programlisting> + The settings from this file are read in at program start and never + written by Ethereal. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command>manuf</command></term> + <listitem> + <para> + Ethereal uses the files listed in <xref linkend="AppFilesTabFolders"/> + to translate the first three bytes of an Ethernet address into a + manufacturers name. This file has the same format as the ethers + file, except addresses are three bytes long. + </para> + <para> + The settings from this file are read in at program start and never + written by Ethereal. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command>ipxnets</command></term> + <listitem> + <para> + Ethereal uses the files listed in <xref linkend="AppFilesTabFolders"/> + to translate IPX network numbers into names. + </para> + <para> + An example is: + <programlisting> +C0.A8.2C.00 HR +c0-a8-1c-00 CEO +00:00:BE:EF IT_Server1 +110f FileServer3 + </programlisting> + </para> + <para> + The settings from this file are read in at program start and never + written by Ethereal. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command>plugins</command></term> + <listitem> + <para> + Ethereal searches for plugins in the directories listed in + <xref linkend="AppFilesTabFolders"/>. + They are searched in the order listed. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> +<!-- </section> --> + +</appendix> +<!-- End of EUG Appendix Files --> diff --git a/docbook/ug-src/EUG_app_howitworks.xml b/docbook/ug-src/EUG_app_howitworks.xml index 58146a798f..83e33beeff 100644 --- a/docbook/ug-src/EUG_app_howitworks.xml +++ b/docbook/ug-src/EUG_app_howitworks.xml @@ -1,104 +1,106 @@ -<!-- EUG Appendix How it Works -->
-<appendix id="AppHowItWorks">
- <title>How Ethereal Works</title>
- <para>
- When using such a complex program like Ethereal, it's sometimes useful to
- understand the mechanisms and concepts behind the surface. This is an
- approach to shed some light on the inner workings of Ethereal.
- </para>
-
- <section><title>Program start</title>
- <para>
- When Etheral starts, a lot of things are done:
- <itemizedlist>
- <listitem>
- initialize the dissectors (register the protocol tree), including plugins
- </listitem>
- <listitem>
- load and set values from the preferences file
- </listitem>
- <listitem>
- load the capture filters from the cfilters file
- </listitem>
- <listitem>
- load the display filters from the dfilters file
- </listitem>
- <listitem>
- load and set the disabled protocols from the disabled_protos file
- </listitem>
- <listitem>
- init libpcap/winpcap (the capturing engine)
- </listitem>
- <listitem>
- process command line parameters
- </listitem>
- <listitem>
- load and set the recently used GUI settings from the recent file
- </listitem>
- <listitem>
- init and show the main screen
- </listitem>
- <listitem>
- if specified by command line, load a capture file or start capturing
- </listitem>
- </itemizedlist>
- </para>
- <para>
-
- </para>
- </section>
-
- <section><title>Protocol dissectors</title>
- <para>
- Each protocol has it's own protocol dissector. A dissector is called from
- Ethereal, if the packet data seems to be of that corresponding protocol. The
- dissector will then process the packet data and call back Ethereal if it
- couldn't dissect all the data in that packet to do any further dissections.
- </para>
- <para>
- So Ethereal will dissect a packet from the lowest to the highest protocol
- layers.
- </para>
- <para>
- But how does Ethereal know, which dissector to choose?
- </para>
- <para>
- At program start, the dissector registers itself at the appropriate place(s).
- There are two ways, how a dissector can register itself for packet data:
- <itemizedlist>
- <listitem>
- <command>static</command> if the dissector knows a specific value
- of a lower layer, if can directly register itself there (e.g. the HTTP
- dissector "knows", that typically the well known TCP port 80 is used to
- transport HTTP data).
- </listitem>
- <listitem>
- <command>heuristic</command> if no such well known way exists, the dissector
- can register itself for the heuristic mechanism. If a lower layer dissector
- has to handle some packet data where no well known way exists, it can
- handover the packet to Ethereal's heuristic mechanism. This will ask all
- registered upper layer dissectors, if they "like" that data. Each of these
- dissectors will typically look into the first few bytes of the packet, if it
- contains some characteristic data of that protocol. So the dissector can
- accept or reject to dissect that packet.
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Let's look at an example: We'll assume, Ethereal loads a TCP/IP/Ethernet
- packet. Ethereal will call the Ethernet dissector, which will dissect the
- Ethernet related data (usually the first 6+6+2 bytes). Then this dissector
- calls back into Ethereal and will pass the rest of the data back to
- Ethereal. Ethereal in turn will call the next related dissector, in our case
- the IP dissector (because of the value 0x800 in the Ethernet type field).
- This game will continue, until no more data has to be dissected, or the data
- is just unknown to Ethereal.
- </para>
- <para>
- You can control the way how Ethereal calls it's dissectors, see <xref
- linkend="ChAdvProtocolDissectionSection"/> for details.
- </para>
- </section>
-
-</appendix>
-<!-- End of EUG Appendix How it Works -->
+<!-- EUG Appendix How it Works --> +<!-- $Id$ --> + +<appendix id="AppHowItWorks"> + <title>How Ethereal Works</title> + <para> + When using such a complex program like Ethereal, it's sometimes useful to + understand the mechanisms and concepts behind the surface. This is an + approach to shed some light on the inner workings of Ethereal. + </para> + + <section><title>Program start</title> + <para> + When Etheral starts, a lot of things are done: + <itemizedlist> + <listitem> + initialize the dissectors (register the protocol tree), including plugins + </listitem> + <listitem> + load and set values from the preferences file + </listitem> + <listitem> + load the capture filters from the cfilters file + </listitem> + <listitem> + load the display filters from the dfilters file + </listitem> + <listitem> + load and set the disabled protocols from the disabled_protos file + </listitem> + <listitem> + init libpcap/winpcap (the capturing engine) + </listitem> + <listitem> + process command line parameters + </listitem> + <listitem> + load and set the recently used GUI settings from the recent file + </listitem> + <listitem> + init and show the main screen + </listitem> + <listitem> + if specified by command line, load a capture file or start capturing + </listitem> + </itemizedlist> + </para> + <para> + + </para> + </section> + + <section><title>Protocol dissectors</title> + <para> + Each protocol has it's own protocol dissector. A dissector is called from + Ethereal, if the packet data seems to be of that corresponding protocol. The + dissector will then process the packet data and call back Ethereal if it + couldn't dissect all the data in that packet to do any further dissections. + </para> + <para> + So Ethereal will dissect a packet from the lowest to the highest protocol + layers. + </para> + <para> + But how does Ethereal know, which dissector to choose? + </para> + <para> + At program start, the dissector registers itself at the appropriate place(s). + There are two ways, how a dissector can register itself for packet data: + <itemizedlist> + <listitem> + <command>static</command> if the dissector knows a specific value + of a lower layer, if can directly register itself there (e.g. the HTTP + dissector "knows", that typically the well known TCP port 80 is used to + transport HTTP data). + </listitem> + <listitem> + <command>heuristic</command> if no such well known way exists, the dissector + can register itself for the heuristic mechanism. If a lower layer dissector + has to handle some packet data where no well known way exists, it can + handover the packet to Ethereal's heuristic mechanism. This will ask all + registered upper layer dissectors, if they "like" that data. Each of these + dissectors will typically look into the first few bytes of the packet, if it + contains some characteristic data of that protocol. So the dissector can + accept or reject to dissect that packet. + </listitem> + </itemizedlist> + </para> + <para> + Let's look at an example: We'll assume, Ethereal loads a TCP/IP/Ethernet + packet. Ethereal will call the Ethernet dissector, which will dissect the + Ethernet related data (usually the first 6+6+2 bytes). Then this dissector + calls back into Ethereal and will pass the rest of the data back to + Ethereal. Ethereal in turn will call the next related dissector, in our case + the IP dissector (because of the value 0x800 in the Ethernet type field). + This game will continue, until no more data has to be dissected, or the data + is just unknown to Ethereal. + </para> + <para> + You can control the way how Ethereal calls it's dissectors, see <xref + linkend="ChAdvProtocolDissectionSection"/> for details. + </para> + </section> + +</appendix> +<!-- End of EUG Appendix How it Works --> diff --git a/docbook/ug-src/EUG_app_messages.xml b/docbook/ug-src/EUG_app_messages.xml index 3654a8d573..602d867a29 100644 --- a/docbook/ug-src/EUG_app_messages.xml +++ b/docbook/ug-src/EUG_app_messages.xml @@ -1,32 +1,34 @@ -<!-- EUG Appendix Messages -->
-<appendix id="AppMessages">
- <title>Ethereal Warnings and Messages</title>
- <section>
- <title>Capture file format not understood</title>
- <para>
- If <application>Ethereal</application> cannot decode the capture
- file format of the file you have asked it to load, you will receive
- a warning box similar to that shown in <xref linkend="AppErr01"/>.
- <figure id="AppErr01">
- <title>Read File Format warning</title>
- <graphic entityref="EtherealFormatError" format="PNG"/>
- </figure>
- </para>
- </section>
-
- <section>
- <title>Save file error</title>
- <para>
- If <application>Ethereal</application> cannot open the file you
- requested it to save captured packets in, you will receive a
- warning box similar to that shown in <xref linkend="AppErr02"/>.
- <figure id="AppErr02"><title>Save Error warning</title>
- <graphic scale="60" entityref="EtherealSaveError" format="JPG"/>
- </figure>
- </para>
- </section>
-
- <!-- Simply add more sections above here ... -->
-
-</appendix>
-<!-- End of EUG Appendix Messages -->
+<!-- EUG Appendix Messages --> +<!-- $Id$ --> + +<appendix id="AppMessages"> + <title>Ethereal Warnings and Messages</title> + <section> + <title>Capture file format not understood</title> + <para> + If <application>Ethereal</application> cannot decode the capture + file format of the file you have asked it to load, you will receive + a warning box similar to that shown in <xref linkend="AppErr01"/>. + <figure id="AppErr01"> + <title>Read File Format warning</title> + <graphic entityref="EtherealFormatError" format="PNG"/> + </figure> + </para> + </section> + + <section> + <title>Save file error</title> + <para> + If <application>Ethereal</application> cannot open the file you + requested it to save captured packets in, you will receive a + warning box similar to that shown in <xref linkend="AppErr02"/>. + <figure id="AppErr02"><title>Save Error warning</title> + <graphic scale="60" entityref="EtherealSaveError" format="JPG"/> + </figure> + </para> + </section> + + <!-- Simply add more sections above here ... --> + +</appendix> +<!-- End of EUG Appendix Messages --> diff --git a/docbook/ug-src/EUG_app_protocols.xml b/docbook/ug-src/EUG_app_protocols.xml index 600b2deffc..a8985346ab 100644 --- a/docbook/ug-src/EUG_app_protocols.xml +++ b/docbook/ug-src/EUG_app_protocols.xml @@ -1,23 +1,25 @@ -<!-- EUG Appendix Protocols -->
-<appendix id="AppProtocols">
- <title>Protocols and Protocol Fields</title>
- <para>
- Ethereal distinguishes between protocols (e.g. tcp) and protocol fields
- (e.g. tcp.port).
- </para>
- <para>
- A comprehensive list of all protocols and protocol fields can be found
- at: <ulink url="&EtherealProtocolsPage;">&EtherealProtocolsPage;</ulink>
- </para>
-
- <para>
- XXX - update this protocols list.
- </para>
-
- <para>
- For a quick reference, the list of available protocols is following:
- &ProtoList;
- </para>
-
-</appendix>
-<!-- End of EUG Appendix Protocols -->
+<!-- EUG Appendix Protocols --> +<!-- $Id$ --> + +<appendix id="AppProtocols"> + <title>Protocols and Protocol Fields</title> + <para> + Ethereal distinguishes between protocols (e.g. tcp) and protocol fields + (e.g. tcp.port). + </para> + <para> + A comprehensive list of all protocols and protocol fields can be found + at: <ulink url="&EtherealProtocolsPage;">&EtherealProtocolsPage;</ulink> + </para> + + <para> + XXX - update this protocols list. + </para> + + <para> + For a quick reference, the list of available protocols is following: + &ProtoList; + </para> + +</appendix> +<!-- End of EUG Appendix Protocols --> diff --git a/docbook/ug-src/EUG_app_tools.xml b/docbook/ug-src/EUG_app_tools.xml index 71b263904d..0831431286 100644 --- a/docbook/ug-src/EUG_app_tools.xml +++ b/docbook/ug-src/EUG_app_tools.xml @@ -1,911 +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 doing some more specialized things. 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 an
- interactive user interface isn't necessary or available. It supports
- the same options as <command>ethereal</command>. 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 files, 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 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 "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/"/>
- </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 ethereal installed to compile the
- code and 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 -->
-
-
+<!-- EUG Appendix Tools --> + +<!-- $Id$ --> + +<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 doing some more specialized things. 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 an + interactive user interface isn't necessary or available. It supports + the same options as <command>ethereal</command>. 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 files, 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 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 "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/"/> + </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 ethereal installed to compile the + code and 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 --> + + diff --git a/docbook/ug-src/EUG_chapter_advanced.xml b/docbook/ug-src/EUG_chapter_advanced.xml index 6e1a86900a..90b81d0889 100644 --- a/docbook/ug-src/EUG_chapter_advanced.xml +++ b/docbook/ug-src/EUG_chapter_advanced.xml @@ -1,280 +1,283 @@ -<!-- EUG Chapter Advanced -->
-<chapter id="ChapterAdvanced">
- <title>Advanced Features</title>
-
- <section id="ChAdvIntroduction"><title>Introduction</title>
- <para>
- In this chapter some advanced features of Ethereal will be described.
- </para>
- </section>
-
- <section id="ChAdvFollowTCPSection"><title>Following TCP streams</title>
- <para>
- There will be occasions when you would like to see the data from a TCP
- session in the order that the application layer sees it. Perhaps
- you are looking for passwords in a Telnet stream, or you are
- trying to make sense of a data stream. If so, Ethereal's ability to
- follow a TCP stream will be useful to you.
- </para>
- <para>
- Simply select a TCP packet in the stream/connection you are interested
- in and then select the Follow TCP Stream menu item from the Ethereal
- Tools menu. Ethereal will pop up a separate window with all the data
- from the TCP stream laid out in order, as shown in
- <xref linkend="ChAdvFollowStream"/>.
- </para>
- <section><title>The "Follow TCP stream" dialog box </title>
- <figure id="ChAdvFollowStream">
- <title>The "Follow TCP Stream" dialog box</title>
- <graphic entityref="EtherealFollowStream" format="PNG"/>
- </figure>
- <para>
- You can choose from the following actions:
- <orderedlist>
- <listitem>
- <para>
- <command>Save As</command> Save the stream data in the currently
- selected format.
- </para>
- </listitem>
- <listitem>
- <para>
- <command>Print</command> Print the stream data in the currently
- selected format.
- </para>
- </listitem>
- <listitem>
- <para>
- <command>Direction</command> Choose the stream direction to be
- displayed ("Entire conversation", "data from A to B only" or "data
- from B to A only").
- </para>
- </listitem>
- <listitem>
- <para>
- <command>Filter out this stream</command> Apply a display filter
- removing the current TCP stream data from the display.
- </para>
- </listitem>
- <listitem>
- <para>
- <command>Close</command> Close this dialog box.
- </para>
- </listitem>
- </orderedlist>
- </para>
- <para>
- You can then choose to view the data in one of four formats:
- <orderedlist>
- <listitem>
- <para>
- <command>ASCII</command>. In this view you see the data from
- each end in ASCII, but alternating according to when each
- end sent data. Unfortunately, non-printing characters do not
- print.
- </para>
- </listitem>
- <listitem>
- <para>
- <command>EBCDIC</command>. For the big-iron freaks out there.
- </para>
- </listitem>
- <listitem>
- <para>
- <command>HEX Dump</command>. This allows you to see all the
- data, but you lose the ability to read it in ASCII.
- </para>
- </listitem>
- <listitem>
- <para>
- <command>C Arrays</command>. This allows you to import the stream data
- into your own C program.
- </para>
- </listitem>
- </orderedlist>
- </para>
- <note>
- <title>Note!</title>
- <para>
- It is worthwhile noting that Follow TCP Stream installs a filter
- to select all the packets in the TCP stream you have selected.
- </para>
- </note>
- </section>
- </section>
-
- <section id="ChAdvReassemblySection"><title>Packet Reassembling/Desegmenting</title>
- <para>
- XXX - rework this chapter, as it's still a bit confusing.
- </para>
- <section><title>What is it?</title>
- <para>
- Often network protocols needs to transport large chunks of data, which are
- complete in itself, e.g. when transferring a file. The underlying
- protocol might not be able to handle that chunk size (e.g. limitation of
- the network packet size), or is stream-based like TCP, which doesn't know
- data chunks at all.
- </para>
- <para>
- In that case the network protocol has to handle that chunks itself and
- (if required) spreading the data over multiple packets. It also needs a
- mechanism to find back the chunk boundaries on the receiving side.
- </para>
- <note><title>Reassembling vs. Desegmenting!</title>
- <para>
- Desegmenting is a slightly different mechanism compared to reassembling,
- but doing the same thing. Both mechanisms combine traffic back together,
- in this chapter only the term reassembling will be used.
- </para>
- </note>
- </section>
- <section><title>How Ethereal handles it</title>
- <para>
- For some of the network protocols Ethereal knows of, a mechanism is
- implemented to find, decode and display this chunks of data.
- Ethereal will try to find the corresponding packets of this chunk,
- and will show the combined data as additional pages in the
- "Packet Bytes" pane, see <xref linkend="ChUsePacketBytesPaneSection"/>.
- </para>
- <note><title>Note!</title>
- <para>
- Reassembling might take place in several protocol layers, so it's possible
- that multiple tabs in the "Packet Bytes" pane appear.
- </para>
- </note>
- <note><title>Note!</title>
- <para>
- You will find the reassembled data in the last packet of the chunk.
- </para>
- </note>
- <para>
- Some examples:
- <itemizedlist>
- <listitem>
- <para>
- In a <command>HTTP</command> GET response, the requested data (e.g. a
- HTML page) is returned. Ethereal will show the hex dump of the data in
- a new tab "Uncompressed entity body" in the "Packet Bytes" pane.
- </para>
- </listitem>
- <listitem>
- <para>
- A <command>DCE-RPC</command> (Remote Procedure Call) client send a
- request to the server and expects a response back from it. Both the
- request and the response is a complete chunk of data and will be
- shown as a new tab "Reassembled DCE/RPC" in the "Packet Bytes" pane.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </section>
-
- <section><title>Reassembling is disabled!</title>
- <para>
- Reassembling is usually disabled in the preferences by default, as it
- slows down packet processing a bit.
- </para>
- <para>
- Enabling reassembling of a protocol typically requires two things:
- <orderedlist>
- <listitem>
- <para>
- the lower level protocol (e.g., TCP) must support
- reassembly. Often this reassembly can be enabled or disabled at will
- via the protocol preferences.
- </para>
- </listitem>
- <listitem>
- <para>
- the higher level protocol (e.g., HTTP) must use the
- reassembly mechanism to reassemble fragmented protocol data. This too
- can often be enabled or disabled via the protocol preferences.
- </para>
- </listitem>
- </orderedlist>
- </para>
- <para>
- As a result, if reassembly of protocol Y on top of protocol X
- must be enabled, it is wise to take a look at the protocol preferences for
- both protocols. Check whether protocol X allows subdissectors to
- reassemble, and check whether protocol Y supports reassembly
- and has it enabled.
- </para>
- <para>
- For example: if you have HTTP on top of TCP, you have to enable the TCP
- preference "Allow subdissectors to reassemble" and enable the HTTP
- preference "Reassemble".
- </para>
- </section>
- </section>
-
- <section id="ChAdvNameResolutionSection"><title>Name Resolution</title>
- <para>
- Name resolution tries to resolve some of the address values to human
- readable names. This conversion might fail. For example, the name might be
- unknown. Some of the lookups are done with data from your local
- machine, while others asking network services such as DNS.
- </para>
- <para>
- XXX - add ipxnets name resolution explanation.
- </para>
- <note><title>Note!</title>
- <para>
- You might see packets to/from your machine in your capture file, which are
- caused by name resolution network services (e.g. DNS packets).
- </para>
- </note>
- <note><title>Note!</title>
- <para>
- The resolved names are not stored in the capture file or somewhere else,
- so the resolved names might not be available if you open the capture file
- later or on another machine.
- </para>
- </note>
- <para>
- The name resolution feature can be en-/disabled separately for the
- following protocol layers:
- </para>
- <section><title>MAC Layer</title>
- <para><command>ARP name resolution</command>
- Convert an ethernet address to the corresponding IP address
- (e.g. 00:09:5b:01:02:03 -> 192.168.0.1).
- </para>
- <para><command>Ethernet manufacturer codes</command>
- If the ARP name resolution failed, Ethereal tries to convert the first 3
- bytes of an ethernet address to an abbreviated manufacturer name, which
- has been assigned by the IETF (e.g. 00:09:5b:01:02:03 -> Netgear_01:02:03).
- </para>
- </section>
- <section><title>Network Layer</title>
- <para><command>DNS name resolution</command>
- Convert an IP address to the hostname associated with it
- (e.g. 65.208.228.223 -> www.ethereal.com).
- </para>
- <warning>
- <title>Warning!</title>
- <para>
- Enabling network name resolution when your name server is
- unavailable may significantly slow Ethereal while it waits
- for all of the name server requests to time out. Use ADNS in that
- case.
- </para>
- </warning>
- </section>
- <section><title>Transport Layer</title>
- <para><command>TCP/UDP port conversion</command>
- Convert a TCP or UDP port to its well known name (e.g. 80 -> http).
- </para>
- </section>
- <section><title>ADNS</title>
- <para>
- As noted, DNS lookups can significantly slow down Ethereal and make it
- appear frozen, which can be very annoying. To solve this, Ethereal can use
- the ADNS library, which handles DNS calls asynchronously.
- </para>
- </section>
- </section>
-
-</chapter>
-<!-- End of EUG Chapter Advanced -->
-
+<!-- EUG Chapter Advanced --> + +<!-- $Id: --> + +<chapter id="ChapterAdvanced"> + <title>Advanced Features</title> + + <section id="ChAdvIntroduction"><title>Introduction</title> + <para> + In this chapter some advanced features of Ethereal will be described. + </para> + </section> + + <section id="ChAdvFollowTCPSection"><title>Following TCP streams</title> + <para> + There will be occasions when you would like to see the data from a TCP + session in the order that the application layer sees it. Perhaps + you are looking for passwords in a Telnet stream, or you are + trying to make sense of a data stream. If so, Ethereal's ability to + follow a TCP stream will be useful to you. + </para> + <para> + Simply select a TCP packet in the stream/connection you are interested + in and then select the Follow TCP Stream menu item from the Ethereal + Tools menu. Ethereal will pop up a separate window with all the data + from the TCP stream laid out in order, as shown in + <xref linkend="ChAdvFollowStream"/>. + </para> + <section><title>The "Follow TCP stream" dialog box </title> + <figure id="ChAdvFollowStream"> + <title>The "Follow TCP Stream" dialog box</title> + <graphic entityref="EtherealFollowStream" format="PNG"/> + </figure> + <para> + You can choose from the following actions: + <orderedlist> + <listitem> + <para> + <command>Save As</command> Save the stream data in the currently + selected format. + </para> + </listitem> + <listitem> + <para> + <command>Print</command> Print the stream data in the currently + selected format. + </para> + </listitem> + <listitem> + <para> + <command>Direction</command> Choose the stream direction to be + displayed ("Entire conversation", "data from A to B only" or "data + from B to A only"). + </para> + </listitem> + <listitem> + <para> + <command>Filter out this stream</command> Apply a display filter + removing the current TCP stream data from the display. + </para> + </listitem> + <listitem> + <para> + <command>Close</command> Close this dialog box. + </para> + </listitem> + </orderedlist> + </para> + <para> + You can then choose to view the data in one of four formats: + <orderedlist> + <listitem> + <para> + <command>ASCII</command>. In this view you see the data from + each end in ASCII, but alternating according to when each + end sent data. Unfortunately, non-printing characters do not + print. + </para> + </listitem> + <listitem> + <para> + <command>EBCDIC</command>. For the big-iron freaks out there. + </para> + </listitem> + <listitem> + <para> + <command>HEX Dump</command>. This allows you to see all the + data, but you lose the ability to read it in ASCII. + </para> + </listitem> + <listitem> + <para> + <command>C Arrays</command>. This allows you to import the stream data + into your own C program. + </para> + </listitem> + </orderedlist> + </para> + <note> + <title>Note!</title> + <para> + It is worthwhile noting that Follow TCP Stream installs a filter + to select all the packets in the TCP stream you have selected. + </para> + </note> + </section> + </section> + + <section id="ChAdvReassemblySection"><title>Packet Reassembling/Desegmenting</title> + <para> + XXX - rework this chapter, as it's still a bit confusing. + </para> + <section><title>What is it?</title> + <para> + Often network protocols needs to transport large chunks of data, which are + complete in itself, e.g. when transferring a file. The underlying + protocol might not be able to handle that chunk size (e.g. limitation of + the network packet size), or is stream-based like TCP, which doesn't know + data chunks at all. + </para> + <para> + In that case the network protocol has to handle that chunks itself and + (if required) spreading the data over multiple packets. It also needs a + mechanism to find back the chunk boundaries on the receiving side. + </para> + <note><title>Reassembling vs. Desegmenting!</title> + <para> + Desegmenting is a slightly different mechanism compared to reassembling, + but doing the same thing. Both mechanisms combine traffic back together, + in this chapter only the term reassembling will be used. + </para> + </note> + </section> + <section><title>How Ethereal handles it</title> + <para> + For some of the network protocols Ethereal knows of, a mechanism is + implemented to find, decode and display this chunks of data. + Ethereal will try to find the corresponding packets of this chunk, + and will show the combined data as additional pages in the + "Packet Bytes" pane, see <xref linkend="ChUsePacketBytesPaneSection"/>. + </para> + <note><title>Note!</title> + <para> + Reassembling might take place in several protocol layers, so it's possible + that multiple tabs in the "Packet Bytes" pane appear. + </para> + </note> + <note><title>Note!</title> + <para> + You will find the reassembled data in the last packet of the chunk. + </para> + </note> + <para> + Some examples: + <itemizedlist> + <listitem> + <para> + In a <command>HTTP</command> GET response, the requested data (e.g. a + HTML page) is returned. Ethereal will show the hex dump of the data in + a new tab "Uncompressed entity body" in the "Packet Bytes" pane. + </para> + </listitem> + <listitem> + <para> + A <command>DCE-RPC</command> (Remote Procedure Call) client send a + request to the server and expects a response back from it. Both the + request and the response is a complete chunk of data and will be + shown as a new tab "Reassembled DCE/RPC" in the "Packet Bytes" pane. + </para> + </listitem> + </itemizedlist> + </para> + </section> + + <section><title>Reassembling is disabled!</title> + <para> + Reassembling is usually disabled in the preferences by default, as it + slows down packet processing a bit. + </para> + <para> + Enabling reassembling of a protocol typically requires two things: + <orderedlist> + <listitem> + <para> + the lower level protocol (e.g., TCP) must support + reassembly. Often this reassembly can be enabled or disabled at will + via the protocol preferences. + </para> + </listitem> + <listitem> + <para> + the higher level protocol (e.g., HTTP) must use the + reassembly mechanism to reassemble fragmented protocol data. This too + can often be enabled or disabled via the protocol preferences. + </para> + </listitem> + </orderedlist> + </para> + <para> + As a result, if reassembly of protocol Y on top of protocol X + must be enabled, it is wise to take a look at the protocol preferences for + both protocols. Check whether protocol X allows subdissectors to + reassemble, and check whether protocol Y supports reassembly + and has it enabled. + </para> + <para> + For example: if you have HTTP on top of TCP, you have to enable the TCP + preference "Allow subdissectors to reassemble" and enable the HTTP + preference "Reassemble". + </para> + </section> + </section> + + <section id="ChAdvNameResolutionSection"><title>Name Resolution</title> + <para> + Name resolution tries to resolve some of the address values to human + readable names. This conversion might fail. For example, the name might be + unknown. Some of the lookups are done with data from your local + machine, while others asking network services such as DNS. + </para> + <para> + XXX - add ipxnets name resolution explanation. + </para> + <note><title>Note!</title> + <para> + You might see packets to/from your machine in your capture file, which are + caused by name resolution network services (e.g. DNS packets). + </para> + </note> + <note><title>Note!</title> + <para> + The resolved names are not stored in the capture file or somewhere else, + so the resolved names might not be available if you open the capture file + later or on another machine. + </para> + </note> + <para> + The name resolution feature can be en-/disabled separately for the + following protocol layers: + </para> + <section><title>MAC Layer</title> + <para><command>ARP name resolution</command> + Convert an ethernet address to the corresponding IP address + (e.g. 00:09:5b:01:02:03 -> 192.168.0.1). + </para> + <para><command>Ethernet manufacturer codes</command> + If the ARP name resolution failed, Ethereal tries to convert the first 3 + bytes of an ethernet address to an abbreviated manufacturer name, which + has been assigned by the IETF (e.g. 00:09:5b:01:02:03 -> Netgear_01:02:03). + </para> + </section> + <section><title>Network Layer</title> + <para><command>DNS name resolution</command> + Convert an IP address to the hostname associated with it + (e.g. 65.208.228.223 -> www.ethereal.com). + </para> + <warning> + <title>Warning!</title> + <para> + Enabling network name resolution when your name server is + unavailable may significantly slow Ethereal while it waits + for all of the name server requests to time out. Use ADNS in that + case. + </para> + </warning> + </section> + <section><title>Transport Layer</title> + <para><command>TCP/UDP port conversion</command> + Convert a TCP or UDP port to its well known name (e.g. 80 -> http). + </para> + </section> + <section><title>ADNS</title> + <para> + As noted, DNS lookups can significantly slow down Ethereal and make it + appear frozen, which can be very annoying. To solve this, Ethereal can use + the ADNS library, which handles DNS calls asynchronously. + </para> + </section> + </section> + +</chapter> +<!-- End of EUG Chapter Advanced --> + diff --git a/docbook/ug-src/EUG_chapter_build_install.xml b/docbook/ug-src/EUG_chapter_build_install.xml index 56ec529ceb..b3b13a7729 100644 --- a/docbook/ug-src/EUG_chapter_build_install.xml +++ b/docbook/ug-src/EUG_chapter_build_install.xml @@ -1,518 +1,520 @@ -<!-- EUG Chapter BuildInstall -->
-<chapter id="ChapterBuildInstall">
- <title>Building and Installing Ethereal</title>
- <section id="ChBuildInstallIntro">
- <title>Introduction</title>
- <para>
- As with all things, there must be a beginning, and so it is with
- Ethereal. To use Ethereal, you must:
- <itemizedlist>
- <listitem>
- <para>
- Obtain a binary package for your operating system, or
- </para>
- </listitem>
- <listitem>
- <para>
- Obtain the source and build Ethereal for your operating system.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Currently, only two or three Linux distributions ship Ethereal, and
- they are commonly shipping an out-of-date version. No other versions
- of UNIX ship Ethereal so far, and Microsoft does not ship it with any
- version of Windows. For that reason, you will need to know where to
- get the latest version of Ethereal and how to install it.
- </para>
- <para>
- This chapter shows you how to obtain source and binary packages,
- and how to build Ethereal from source, should you choose to do so.
- </para>
- <para>
- The following are the general steps you would use:
- <orderedlist>
- <listitem>
- <para>
- Download the relevant package for your needs, e.g. source or
- binary distribution.
- </para>
- </listitem>
- <listitem>
- <para>
- Build the source into a binary, if you have downloaded the
- source.
- </para>
- <para>
- This may involve building and/or installing other necessary packages.
- </para>
- </listitem>
- <listitem>
- <para>
- Install the binaries into their final destinations.
- </para>
- </listitem>
- </orderedlist>
- </para>
- </section>
-
- <section id="ChBuildInstallDistro">
- <title>Obtaining the source and binary distributions</title>
- <para>
- You can obtain both source and binary distributions from the Ethereal
- web site: <ulink url="&EtherealWebSite;">&EtherealWebSite;</ulink>.
- Simply select the download link, and then select either the source
- package or binary package of your choice from the mirror site closest
- to you.
- </para>
- <note>
- <title>Download all the needed files</title>
- <para>
- In general, unless you have already downloaded Ethereal
- before, you will most likely need to download several source
- packages if you are building Ethereal from source. This is
- covered in more detail below. <!-- Make a ref -->
- </para>
- </note>
- <para>
- Once you have downloaded the relevant files, you can go on to the
- next step.
- </para>
- <note>
- <title>Note!</title>
- <para>
- While you will find a number of binary packages available on the
- Ethereal web site, you might not find one for your platform, and
- they often tend to be several versions behind the current released
- version, as they are contributed by people who have the platforms
- they are built for.
- </para>
- <para>
- For this reason, you might want to pull down the source distribution
- and build it, as the process is relatively simple.
- </para>
- </note>
- </section>
-
- <section id="ChBuildInstallBeforeBuild">
- <title>Before you build <application>Ethereal</application></title>
- <para>
- Before you build Ethereal from sources, or install a binary package,
- you must ensure that you have the following other packages installed:
- <itemizedlist>
- <listitem>
- <para>GTK+, The GIMP Tool Kit.</para>
- <para>
- You will also need Glib. Both can be obtained from
- <ulink url="http://www.gtk.org">www.gtk.org</ulink>
- </para>
- </listitem>
- <listitem>
- <para>
- libpcap, the packet capture software that Ethereal uses.
- </para>
- <para>
- You can obtain libpcap from
- <ulink url="http://www.tcpdump.org">www.tcpdump.org</ulink>
- </para>
- </listitem>
- </itemizedlist>
- Depending on your system, you may be able to install these from
- binaries, e.g. RPMs, or you may need to obtain them in source code
- form and build them.
- </para>
- <para>
- If you have downloaded the source for GTK+, the instructions shown
- in <xref linkend="Ch02Ex1"/> may provide some help in building it:
- <example id="Ch02Ex1">
- <title>Building GTK+ from source</title>
- <programlisting>
-gzip -dc gtk+-1.2.10.tar.gz | tar xvf -
-<much output removed>
-cd gtk+-1.2.10
-./configure
-<much output removed>
-make
-<much output removed>
-make install
-<much output removed>
- </programlisting>
- </example>
- <note>
- <title>Note!</title>
- <para>
- You may need to change the version number of gtk+ in
- <xref linkend="Ch02Ex1"/> to match the version of GTK+ you have
- downloaded. The directory you change to will change if the
- version of GTK+ changes, and in all cases,
- <command>tar xvf -</command> will show you the name of the
- directory you should change to.
- </para>
- </note>
- <note>
- <title>Note!</title>
- <para>
- If you use Linux, or have GNU <command>tar</command> installed,
- you can use <command>tar zxvf gtk+-1.2.10.tar.gz</command>. It
- is also possible to use <command>gunzip -c</command> or
- <command>gzcat</command> rather than <command>gzip -dc</command>
- on many UNIX systems.
- </para>
- </note>
- <note>
- <title>Note!</title>
- <para>
- If you downloaded gtk+ or any other tar file using Windows,
- you may find your file called gtk+-1_2_8_tar.gz.
- </para>
- </note>
- </para>
- <para>
- You should consult the GTK+ web site if any errors occur in carrying
- out the instructions in <xref linkend="Ch02Ex1"/>.
- </para>
- <para>
- If you have downloaded the source to libpcap, the general instructions
- shown in <xref linkend="Ch2Ex2"/> will assist in building it. Also,
- if your operating system does not support <command>tcpdump</command>,
- you might also want to download it from the
- <ulink url="http://www.tcpdump.org">tcpdump</ulink> web site and
- install it.
- <example id="Ch2Ex2">
- <title>Building and installing libpcap</title>
- <programlisting>
-gzip -dc libpcap-0.8.3.tar.Z | tar xvf -
-<much output removed>
-cd libpcap_0_8_3
-./configure
-<much output removed>
-make
-<much output removed>
-make install
-<much output removed>
-make install-incl
-<much output removed>
- </programlisting>
- </example>
- </para>
- <note>
- <title>Note!</title>
- <para>
- The directory you should change to will depend on the version of
- libpcap you have downloaded. In all cases,
- <command>tar xvf -</command> will show you the name of the
- directory that has been unpacked.
- </para>
- </note>
- <para>
- When installing the include files, you might get the error shown
- in <xref linkend="Ch02Ex3"/> when you submit the command
- <command>make install-incl</command>.
- <example id="Ch02Ex3">
- <title>Errors while installing the libpcap include files</title>
- <programlisting>
-/usr/local/include/pcap.h
-/usr/bin/install -c -m 444 -o bin -g bin ./pcap-namedb.h \
-/usr/local/include/pcap-namedb.h
-/usr/bin/install -c -m 444 -o bin -g bin ./net/bpf.h \
-/usr/local/include/net/bpf.h
-/usr/bin/install: cannot create regular file \
-`/usr/local/include/net/bpf.h': No such file or directory
-make: *** [install-incl] Error 1
- </programlisting>
- </example>
- If you do, simply create the missing directory with the following
- command:
- <programlisting>
-mkdir /usr/local/include/net
- </programlisting>
- and rerun the command <command>make install-incl</command>.
- </para>
- <para>
- Under RedHat 6.x and beyond (and distributions based on it, like
- Mandrake) you can simply install each of the packages you need from
- RPMs. Most Linux systems will install GTK+ and Glib in anycase,
- however, you will probably need to install the devel versions of
- each of these packages. The commands shown in <xref linkend="Ch02Ex4"/>
- will install all the needed RPMs if they are not already installed.
- <example id="Ch02Ex4">
- <title>
- Installing required RPMs under RedHat Linux 6.2 and beyond
- </title>
- <programlisting>
-cd /mnt/cdrom/RedHat/RPMS
-rpm -ivh glib-1.2.6-3.i386.rpm
-rpm -ivh glib-devel-1.2.6-3.i386.rpm
-rpm -ivh gtk+-1.2.6-7.i386.rpm
-rpm -ivh gtk+-devel-1.2.6-7.i386.rpm
-rpm -ivh libpcap-0.4-19.i386.rpm
- </programlisting>
- </example>
- </para>
- <note>
- <para>
- If you are using a version of RedHat later than 6.2, the required
- RPMs have most likely changed. Simply use the correct RPMs from your
- distribution.
- </para>
- </note>
- <para>
- Under Debian you can install Ethereal using apt-get. apt-get will
- handle any dependency issues for you. <xref linkend="Ch02Ex5"/> shows
- how to do this.
- <example id="Ch02Ex5">
- <title>Installing debs under Debian</title>
- <programlisting>
-apt-get install ethereal
- </programlisting>
- </example>
- </para>
- </section>
-
- <section id="ChBuildInstallUnixBuild">
- <title>Building Ethereal from source under UNIX</title>
- <para>
- Use the following general steps if you are building Ethereal from
- source under a UNIX operating system:
- <orderedlist>
- <listitem>
- <para>
- Unpack the source from its <command>gzip</command>'d
- <command>tar</command> file. If you are using Linux, or your
- version of UNIX uses GNU <command>tar</command>, you can use the
- following command:
- <programlisting>
-tar zxvf ethereal-&EtherealCurrentVersionTarFile;-tar.gz
- </programlisting>
- </para>
- <para>
- For other versions of UNIX, You will want to use the following
- commands:
- <programlisting>
-gzip -d ethereal-&EtherealCurrentVersionTarFile;-tar.gz
-tar xvf ethereal-&EtherealCurrentVersionTarFile;-tar
- </programlisting>
- <note>
- <title>Note!</title>
- <para>
- The pipeline
- <command>
- gzip -dc ethereal-&EtherealCurrentVersionTarFile;-tar.gz | tar xvf -
- </command> will work here as well.
- </para>
- </note>
- <note>
- <title>Note!</title>
- <para>
- If you have downloaded the Ethereal tarball under Windows,
- you may find that your browser has created a file with
- underscores rather than periods in its file name.
- </para>
- </note>
- </para>
- </listitem>
- <listitem>
- <para>
- Change directory to the Ethereal source directory.
- </para>
- </listitem>
- <listitem>
- <para>
- Configure your source so it will build correctly for your
- version of UNIX. You can do this with the following command:
- <programlisting>
-./configure
- </programlisting>
- </para>
- <para>
- If this step fails, you will have to rectify the problems and
- rerun <command>configure</command>. Troubleshooting hints are
- provided in <xref linkend="ChBuildInstallUnixTrouble"/>.
- </para>
- </listitem>
- <listitem>
- <para>
- Build the sources into a binary, with the <command>make</command>
- command. For example:
- <programlisting>
-make
- </programlisting>
- </para>
- </listitem>
- <listitem>
- <para>
- Install the software in its final destination, using the command:
- <programlisting>
-make install
- </programlisting>
- </para>
- </listitem>
- </orderedlist>
- </para>
- <para>
- Once you have installed Ethereal with <command>make install</command>
- above, you should be able to run it by entering
- <command>ethereal</command>.
- </para>
- </section>
-
- <section id="ChBuildInstallUnixInstallBins">
- <title>Installing the binaries under UNIX</title>
- <para>
- In general, installing the binary under your version of UNIX will be
- specific to the installation methods used with your version of UNIX.
- For example, under AIX, you would use <command>smit</command> to
- install the Ethereal binary package, while under Tru64 UNIX
- (formerly Digital UNIX) you would use <command>setld</command>.
- </para>
-
- <section>
- <title>Installing from rpm's under RedHat and alike</title>
- <para>
- Use the following command to install the Ethereal RPM that you have
- downloaded from the Ethereal web site:
- <programlisting>
-rpm -ivh ethereal-0.10.5-0.2.2.i386.rpm
- </programlisting>
- If the above step fails because of missing dependencies, install the
- dependencies first, and then retry the step above. See
- <xref linkend="Ch02Ex4"/> for information on what RPMs you will need
- to have installed.
- </para>
- </section>
-
- <section>
- <title>Installing from deb's under Debian</title>
- <para>
- Use the following command to install Ethereal under Debian:
- <programlisting>
-apt-get install ethereal
- </programlisting>
- apt-get should take care of all of the dependency issues for you.
- </para>
- </section>
- </section>
-
- <section id="ChBuildInstallUnixTrouble">
- <title>Troubleshooting during the install on Unix</title>
- <para>
- A number of errors can occur during the installation process.
- Some hints on solving these are provided here.
- </para>
- <para>
- If the <command>configure</command> stage fails, you will need to find
- out why. You can check the file <filename>config.log</filename> in the
- source directory to find out what failed. The last few lines of this
- file should help in determining the problem.
- </para>
- <para>
- The standard problems are that you do not have GTK+ on your system,
- or you do not have a recent enough version of GTK+. The
- <command>configure</command> will also fail if you do not have libpcap
- (at least the required include files) on your system.
- </para>
- <para>
- Another common problem is for the final compile and link stage to
- terminate with a complaint of: <errorname>Output too long.</errorname>
- This is likely to be caused by an antiquated <command>sed</command>
- (such as the one shipped with Solaris). Since <command>sed</command> is
- used by the <command>libtool</command> script to construct the final
- link command, this leads to mysterious problems. This can be
- resolved by downloading a recent version of sed from
- <ulink url="http://www.gnu.org/directory/sed.html">
- http://www.gnu.org/directory/sed.html
- </ulink>.
- </para>
- <para>
- If you cannot determine what the problems are, send mail to the
- <command>ethereal-dev</command> mailing list explaining your problem,
- and including the output from <filename>config.log</filename> and
- anything else you think is relevant, like a trace of the
- <command>make</command> stage.
- </para>
- </section>
-
- <section id="ChBuildInstallWinBuild">
- <title>Building from source under Windows</title>
- <para>
- It is recommended to use the binary installer for Windows,
- until you want to start developing Ethereal on this platform.
- </para>
- <para>
- For further information how to build Ethereal for Windows from the
- sources, have a look at the file Readme.win32, which
- can be found in the doc directory of the sources.
- </para>
- </section>
-
- <section id="ChBuildInstallWinInstall">
- <title>Installing Ethereal under Windows</title>
- <para>
- In this section we explore installing Ethereal under Windows from the
- binary packages. You must follow two steps:
- <orderedlist>
- <listitem>
- <para>
- Install WinPcap. You will find a single installer exe called something
- like "auto-installer", which can be installed under various Windows
- systems, including 9x/Me/NT4.0/2000/XP. This installer is located at:
- <ulink url="&WinPcapDownloadWebsite;">&WinPcapDownloadWebsite;</ulink>.
- You should download the latest released version (the latest one not
- marked "beta") and execute it.
- </para>
- </listitem>
- <listitem>
- <para>
- Install Ethereal. You may acquire a binary installable of
- Ethereal at
- <ulink url="&EtherealBinariesPage;">&EtherealBinariesPage;</ulink>.
- Download the installer and execute it.
- </para>
- </listitem>
- </orderedlist>
- Both steps are extremely simply, as you only have to download and
- install the two exe files.
- </para>
- <section id="ChBuildInstallWinUpdate">
- <title>Update</title>
- <para>
- From time to time you may want to update your installed Ethereal to a more
- recent version. If you join Ethereal's announce mailing list, you will be
- informed about new Ethereal versions, see <xref
- linkend="ChIntroMailingLists"/> for details how to subscribe to this list.
- <itemizedlist>
- <listitem>
- <para>
- <command>Update Ethereal</command>.
- New versions of Ethereal usually become available every 4-8 weeks.
- Updating Ethereal is done the same way as installing it, you simply
- download and start the installer exe. A reboot is usually not required and
- all your personal settings remain unchanged.
- </para>
- </listitem>
- <listitem>
- <para>
- <command>Update WinPcap</command>.
- New versions of WinPcap are less frequently available, maybe only once a
- year. You will find WinPcap update instructions where you can download new
- versions. Usually you have to reboot the machine after installing a new
- WinPcap version.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </section>
-
- <section id="ChBuildInstallWinUninstall">
- <title>Uninstall Ethereal</title>
- <para>
- You can uninstall Ethereal the usual way, using the Software option
- inside the Control Panel. You will find two entries, one for Ethereal
- itself and one for WinPcap.
- </para>
- </section>
- </section>
-
-</chapter>
-<!-- End of EUG Chapter 2 -->
+<!-- EUG Chapter BuildInstall --> +<!-- $Id$ --> + +<chapter id="ChapterBuildInstall"> + <title>Building and Installing Ethereal</title> + <section id="ChBuildInstallIntro"> + <title>Introduction</title> + <para> + As with all things, there must be a beginning, and so it is with + Ethereal. To use Ethereal, you must: + <itemizedlist> + <listitem> + <para> + Obtain a binary package for your operating system, or + </para> + </listitem> + <listitem> + <para> + Obtain the source and build Ethereal for your operating system. + </para> + </listitem> + </itemizedlist> + </para> + <para> + Currently, only two or three Linux distributions ship Ethereal, and + they are commonly shipping an out-of-date version. No other versions + of UNIX ship Ethereal so far, and Microsoft does not ship it with any + version of Windows. For that reason, you will need to know where to + get the latest version of Ethereal and how to install it. + </para> + <para> + This chapter shows you how to obtain source and binary packages, + and how to build Ethereal from source, should you choose to do so. + </para> + <para> + The following are the general steps you would use: + <orderedlist> + <listitem> + <para> + Download the relevant package for your needs, e.g. source or + binary distribution. + </para> + </listitem> + <listitem> + <para> + Build the source into a binary, if you have downloaded the + source. + </para> + <para> + This may involve building and/or installing other necessary packages. + </para> + </listitem> + <listitem> + <para> + Install the binaries into their final destinations. + </para> + </listitem> + </orderedlist> + </para> + </section> + + <section id="ChBuildInstallDistro"> + <title>Obtaining the source and binary distributions</title> + <para> + You can obtain both source and binary distributions from the Ethereal + web site: <ulink url="&EtherealWebSite;">&EtherealWebSite;</ulink>. + Simply select the download link, and then select either the source + package or binary package of your choice from the mirror site closest + to you. + </para> + <note> + <title>Download all the needed files</title> + <para> + In general, unless you have already downloaded Ethereal + before, you will most likely need to download several source + packages if you are building Ethereal from source. This is + covered in more detail below. <!-- Make a ref --> + </para> + </note> + <para> + Once you have downloaded the relevant files, you can go on to the + next step. + </para> + <note> + <title>Note!</title> + <para> + While you will find a number of binary packages available on the + Ethereal web site, you might not find one for your platform, and + they often tend to be several versions behind the current released + version, as they are contributed by people who have the platforms + they are built for. + </para> + <para> + For this reason, you might want to pull down the source distribution + and build it, as the process is relatively simple. + </para> + </note> + </section> + + <section id="ChBuildInstallBeforeBuild"> + <title>Before you build <application>Ethereal</application></title> + <para> + Before you build Ethereal from sources, or install a binary package, + you must ensure that you have the following other packages installed: + <itemizedlist> + <listitem> + <para>GTK+, The GIMP Tool Kit.</para> + <para> + You will also need Glib. Both can be obtained from + <ulink url="http://www.gtk.org">www.gtk.org</ulink> + </para> + </listitem> + <listitem> + <para> + libpcap, the packet capture software that Ethereal uses. + </para> + <para> + You can obtain libpcap from + <ulink url="http://www.tcpdump.org">www.tcpdump.org</ulink> + </para> + </listitem> + </itemizedlist> + Depending on your system, you may be able to install these from + binaries, e.g. RPMs, or you may need to obtain them in source code + form and build them. + </para> + <para> + If you have downloaded the source for GTK+, the instructions shown + in <xref linkend="Ch02Ex1"/> may provide some help in building it: + <example id="Ch02Ex1"> + <title>Building GTK+ from source</title> + <programlisting> +gzip -dc gtk+-1.2.10.tar.gz | tar xvf - +<much output removed> +cd gtk+-1.2.10 +./configure +<much output removed> +make +<much output removed> +make install +<much output removed> + </programlisting> + </example> + <note> + <title>Note!</title> + <para> + You may need to change the version number of gtk+ in + <xref linkend="Ch02Ex1"/> to match the version of GTK+ you have + downloaded. The directory you change to will change if the + version of GTK+ changes, and in all cases, + <command>tar xvf -</command> will show you the name of the + directory you should change to. + </para> + </note> + <note> + <title>Note!</title> + <para> + If you use Linux, or have GNU <command>tar</command> installed, + you can use <command>tar zxvf gtk+-1.2.10.tar.gz</command>. It + is also possible to use <command>gunzip -c</command> or + <command>gzcat</command> rather than <command>gzip -dc</command> + on many UNIX systems. + </para> + </note> + <note> + <title>Note!</title> + <para> + If you downloaded gtk+ or any other tar file using Windows, + you may find your file called gtk+-1_2_8_tar.gz. + </para> + </note> + </para> + <para> + You should consult the GTK+ web site if any errors occur in carrying + out the instructions in <xref linkend="Ch02Ex1"/>. + </para> + <para> + If you have downloaded the source to libpcap, the general instructions + shown in <xref linkend="Ch2Ex2"/> will assist in building it. Also, + if your operating system does not support <command>tcpdump</command>, + you might also want to download it from the + <ulink url="http://www.tcpdump.org">tcpdump</ulink> web site and + install it. + <example id="Ch2Ex2"> + <title>Building and installing libpcap</title> + <programlisting> +gzip -dc libpcap-0.8.3.tar.Z | tar xvf - +<much output removed> +cd libpcap_0_8_3 +./configure +<much output removed> +make +<much output removed> +make install +<much output removed> +make install-incl +<much output removed> + </programlisting> + </example> + </para> + <note> + <title>Note!</title> + <para> + The directory you should change to will depend on the version of + libpcap you have downloaded. In all cases, + <command>tar xvf -</command> will show you the name of the + directory that has been unpacked. + </para> + </note> + <para> + When installing the include files, you might get the error shown + in <xref linkend="Ch02Ex3"/> when you submit the command + <command>make install-incl</command>. + <example id="Ch02Ex3"> + <title>Errors while installing the libpcap include files</title> + <programlisting> +/usr/local/include/pcap.h +/usr/bin/install -c -m 444 -o bin -g bin ./pcap-namedb.h \ +/usr/local/include/pcap-namedb.h +/usr/bin/install -c -m 444 -o bin -g bin ./net/bpf.h \ +/usr/local/include/net/bpf.h +/usr/bin/install: cannot create regular file \ +`/usr/local/include/net/bpf.h': No such file or directory +make: *** [install-incl] Error 1 + </programlisting> + </example> + If you do, simply create the missing directory with the following + command: + <programlisting> +mkdir /usr/local/include/net + </programlisting> + and rerun the command <command>make install-incl</command>. + </para> + <para> + Under RedHat 6.x and beyond (and distributions based on it, like + Mandrake) you can simply install each of the packages you need from + RPMs. Most Linux systems will install GTK+ and Glib in anycase, + however, you will probably need to install the devel versions of + each of these packages. The commands shown in <xref linkend="Ch02Ex4"/> + will install all the needed RPMs if they are not already installed. + <example id="Ch02Ex4"> + <title> + Installing required RPMs under RedHat Linux 6.2 and beyond + </title> + <programlisting> +cd /mnt/cdrom/RedHat/RPMS +rpm -ivh glib-1.2.6-3.i386.rpm +rpm -ivh glib-devel-1.2.6-3.i386.rpm +rpm -ivh gtk+-1.2.6-7.i386.rpm +rpm -ivh gtk+-devel-1.2.6-7.i386.rpm +rpm -ivh libpcap-0.4-19.i386.rpm + </programlisting> + </example> + </para> + <note> + <para> + If you are using a version of RedHat later than 6.2, the required + RPMs have most likely changed. Simply use the correct RPMs from your + distribution. + </para> + </note> + <para> + Under Debian you can install Ethereal using apt-get. apt-get will + handle any dependency issues for you. <xref linkend="Ch02Ex5"/> shows + how to do this. + <example id="Ch02Ex5"> + <title>Installing debs under Debian</title> + <programlisting> +apt-get install ethereal + </programlisting> + </example> + </para> + </section> + + <section id="ChBuildInstallUnixBuild"> + <title>Building Ethereal from source under UNIX</title> + <para> + Use the following general steps if you are building Ethereal from + source under a UNIX operating system: + <orderedlist> + <listitem> + <para> + Unpack the source from its <command>gzip</command>'d + <command>tar</command> file. If you are using Linux, or your + version of UNIX uses GNU <command>tar</command>, you can use the + following command: + <programlisting> +tar zxvf ethereal-&EtherealCurrentVersionTarFile;-tar.gz + </programlisting> + </para> + <para> + For other versions of UNIX, You will want to use the following + commands: + <programlisting> +gzip -d ethereal-&EtherealCurrentVersionTarFile;-tar.gz +tar xvf ethereal-&EtherealCurrentVersionTarFile;-tar + </programlisting> + <note> + <title>Note!</title> + <para> + The pipeline + <command> + gzip -dc ethereal-&EtherealCurrentVersionTarFile;-tar.gz | tar xvf - + </command> will work here as well. + </para> + </note> + <note> + <title>Note!</title> + <para> + If you have downloaded the Ethereal tarball under Windows, + you may find that your browser has created a file with + underscores rather than periods in its file name. + </para> + </note> + </para> + </listitem> + <listitem> + <para> + Change directory to the Ethereal source directory. + </para> + </listitem> + <listitem> + <para> + Configure your source so it will build correctly for your + version of UNIX. You can do this with the following command: + <programlisting> +./configure + </programlisting> + </para> + <para> + If this step fails, you will have to rectify the problems and + rerun <command>configure</command>. Troubleshooting hints are + provided in <xref linkend="ChBuildInstallUnixTrouble"/>. + </para> + </listitem> + <listitem> + <para> + Build the sources into a binary, with the <command>make</command> + command. For example: + <programlisting> +make + </programlisting> + </para> + </listitem> + <listitem> + <para> + Install the software in its final destination, using the command: + <programlisting> +make install + </programlisting> + </para> + </listitem> + </orderedlist> + </para> + <para> + Once you have installed Ethereal with <command>make install</command> + above, you should be able to run it by entering + <command>ethereal</command>. + </para> + </section> + + <section id="ChBuildInstallUnixInstallBins"> + <title>Installing the binaries under UNIX</title> + <para> + In general, installing the binary under your version of UNIX will be + specific to the installation methods used with your version of UNIX. + For example, under AIX, you would use <command>smit</command> to + install the Ethereal binary package, while under Tru64 UNIX + (formerly Digital UNIX) you would use <command>setld</command>. + </para> + + <section> + <title>Installing from rpm's under RedHat and alike</title> + <para> + Use the following command to install the Ethereal RPM that you have + downloaded from the Ethereal web site: + <programlisting> +rpm -ivh ethereal-0.10.5-0.2.2.i386.rpm + </programlisting> + If the above step fails because of missing dependencies, install the + dependencies first, and then retry the step above. See + <xref linkend="Ch02Ex4"/> for information on what RPMs you will need + to have installed. + </para> + </section> + + <section> + <title>Installing from deb's under Debian</title> + <para> + Use the following command to install Ethereal under Debian: + <programlisting> +apt-get install ethereal + </programlisting> + apt-get should take care of all of the dependency issues for you. + </para> + </section> + </section> + + <section id="ChBuildInstallUnixTrouble"> + <title>Troubleshooting during the install on Unix</title> + <para> + A number of errors can occur during the installation process. + Some hints on solving these are provided here. + </para> + <para> + If the <command>configure</command> stage fails, you will need to find + out why. You can check the file <filename>config.log</filename> in the + source directory to find out what failed. The last few lines of this + file should help in determining the problem. + </para> + <para> + The standard problems are that you do not have GTK+ on your system, + or you do not have a recent enough version of GTK+. The + <command>configure</command> will also fail if you do not have libpcap + (at least the required include files) on your system. + </para> + <para> + Another common problem is for the final compile and link stage to + terminate with a complaint of: <errorname>Output too long.</errorname> + This is likely to be caused by an antiquated <command>sed</command> + (such as the one shipped with Solaris). Since <command>sed</command> is + used by the <command>libtool</command> script to construct the final + link command, this leads to mysterious problems. This can be + resolved by downloading a recent version of sed from + <ulink url="http://www.gnu.org/directory/sed.html"> + http://www.gnu.org/directory/sed.html + </ulink>. + </para> + <para> + If you cannot determine what the problems are, send mail to the + <command>ethereal-dev</command> mailing list explaining your problem, + and including the output from <filename>config.log</filename> and + anything else you think is relevant, like a trace of the + <command>make</command> stage. + </para> + </section> + + <section id="ChBuildInstallWinBuild"> + <title>Building from source under Windows</title> + <para> + It is recommended to use the binary installer for Windows, + until you want to start developing Ethereal on this platform. + </para> + <para> + For further information how to build Ethereal for Windows from the + sources, have a look at the file Readme.win32, which + can be found in the doc directory of the sources. + </para> + </section> + + <section id="ChBuildInstallWinInstall"> + <title>Installing Ethereal under Windows</title> + <para> + In this section we explore installing Ethereal under Windows from the + binary packages. You must follow two steps: + <orderedlist> + <listitem> + <para> + Install WinPcap. You will find a single installer exe called something + like "auto-installer", which can be installed under various Windows + systems, including 9x/Me/NT4.0/2000/XP. This installer is located at: + <ulink url="&WinPcapDownloadWebsite;">&WinPcapDownloadWebsite;</ulink>. + You should download the latest released version (the latest one not + marked "beta") and execute it. + </para> + </listitem> + <listitem> + <para> + Install Ethereal. You may acquire a binary installable of + Ethereal at + <ulink url="&EtherealBinariesPage;">&EtherealBinariesPage;</ulink>. + Download the installer and execute it. + </para> + </listitem> + </orderedlist> + Both steps are extremely simply, as you only have to download and + install the two exe files. + </para> + <section id="ChBuildInstallWinUpdate"> + <title>Update</title> + <para> + From time to time you may want to update your installed Ethereal to a more + recent version. If you join Ethereal's announce mailing list, you will be + informed about new Ethereal versions, see <xref + linkend="ChIntroMailingLists"/> for details how to subscribe to this list. + <itemizedlist> + <listitem> + <para> + <command>Update Ethereal</command>. + New versions of Ethereal usually become available every 4-8 weeks. + Updating Ethereal is done the same way as installing it, you simply + download and start the installer exe. A reboot is usually not required and + all your personal settings remain unchanged. + </para> + </listitem> + <listitem> + <para> + <command>Update WinPcap</command>. + New versions of WinPcap are less frequently available, maybe only once a + year. You will find WinPcap update instructions where you can download new + versions. Usually you have to reboot the machine after installing a new + WinPcap version. + </para> + </listitem> + </itemizedlist> + </para> + </section> + + <section id="ChBuildInstallWinUninstall"> + <title>Uninstall Ethereal</title> + <para> + You can uninstall Ethereal the usual way, using the Software option + inside the Control Panel. You will find two entries, one for Ethereal + itself and one for WinPcap. + </para> + </section> + </section> + +</chapter> +<!-- End of EUG Chapter 2 --> diff --git a/docbook/ug-src/EUG_chapter_capture.xml b/docbook/ug-src/EUG_chapter_capture.xml index a0b197c61d..751b658d53 100644 --- a/docbook/ug-src/EUG_chapter_capture.xml +++ b/docbook/ug-src/EUG_chapter_capture.xml @@ -1,787 +1,789 @@ -<!-- EUG Chapter Capture -->
-<chapter id="ChapterCapture">
- <title>Capturing Live Network Data</title>
- <section id="ChCapCapturingSection"><title>Start Capturing</title>
- <para>
- There are two methods you can use to start capturing packets with
- Ethereal:
- <orderedlist>
- <listitem>
- <para>
- From the command line using the following:
- <programlisting>
-ethereal -i eth0 -k
- </programlisting>
- This will start Ethereal capturing on interface eth0.
- </para>
- </listitem>
- <listitem>
- <para>
- By starting Ethereal and then selecting Start... from the
- Capture menu (or use the corresponding item in the "Main" toolbar),
- this brings up the Capture Options dialog box.
- </para>
- </listitem>
- </orderedlist>
- </para>
- </section>
-
- <section id="ChCapCaptureOptions">
- <title>The "Capture Options" dialog box</title>
- <para>
- When you select Start... from the Capture menu, Ethereal pops
- up the "Capture Options" dialog box as shown in
- <xref linkend="ChCapCaptureOptionsDialog"/>.
- </para>
- <figure id="ChCapCaptureOptionsDialog">
- <title>The "Capture Options" dialog box</title>
- <graphic entityref="EtherealCaptureOptionsDialog" format="JPG"/>
- </figure>
- <tip><title>Tip!</title>
- <para>
- If you are unsure which options to choose in this dialog box, just try
- keeping the defaults as this should work well in many cases.
- </para>
- </tip>
- <para>
- You can set the following fields in this dialog box:
- </para>
- <section><title>Capture frame</title>
- <variablelist>
- <varlistentry><term><command>Interface</command></term>
- <listitem>
- <para>
- This field specifies the interface you want to capture on.
- You can only capture on one interface, and you can only
- capture on interfaces that Ethereal has found on the
- system. It is a drop-down list, so simply click on the
- button on the right hand side and select the interface you
- want. It defaults to the first non-loopback interface that
- supports capturing, and if there are none, the first
- loopback interface. On some systems, loopback interfaces
- cannot be used for capturing (loopback interfaces are not available
- on Windows platforms).
- </para>
- <para>
- This field performs the same function as the
- <command>-i <interface></command> command line option.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>Link-layer header type</command></term>
- <listitem>
- <para>
- Unless you are in the rare situation that you need this, just keep
- the default. For a detailed description, see
- <xref linkend="ChCapLinkLayerHeader"/>
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>Buffer size: n megabyte(s)</command></term>
- <listitem>
- <para>
- Enter the buffer size to be used while capturing. This is the size
- of the kernel buffer which will keep the captured packets, until
- they are written to disk. If you encounter packet drops, try
- increasing this value.
- </para>
- <note>
- <title>Note</title>
- <para>This option is only available on Windows platforms.</para>
- </note>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <command>Capture packets in promiscuous mode</command>
- </term>
- <listitem>
- <para>
- This checkbox allows you to specify that Ethereal
- should put the interface in promiscuous mode when capturing.
- If you do not specify this, Ethereal will only capture the
- packets going to or from your computer (not
- all packets on your LAN segment).
- </para>
- <note>
- <title>Note</title>
- <para>
- If some other process has put the interface in
- promiscuous mode you may be capturing in promiscuous
- mode even if you turn off this option
- </para>
- </note>
- <note>
- <title>Note</title>
- <para>
- Even in promiscuous mode you still won't necessarily see all packets
- on your LAN segment, see <ulink url="&EtherealFAQPromiscPage;"/> for
- some more explanations.
- </para>
- </note>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>Limit each packet to n bytes</command></term>
- <listitem>
- <para>
- This field allows you to specify the maximum amount of
- data that will be captured for each packet, and is
- sometimes referred to as the <command>snaplen</command>. If disabled,
- the default is 65535, which will be sufficient for most
- protocols. Some rules of thumb:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- If you are unsure, just keep the default value.
- </para>
- </listitem>
- <listitem>
- <para>
- If you don't need all of the data in a packet - for example, if you
- only need the link-layer, IP, and TCP headers - you might want to
- choose a small snapshot length, as less CPU time is required for
- copying packets, less buffer space is required for packets, and thus
- perhaps fewer packets will be dropped if traffic is very heavy.
- </para>
- </listitem>
- <listitem>
- <para>
- If you don't capture all of the data in a packet, you might find that
- the packet data you want is in the part that's dropped, or that
- reassembly isn't possible as the data required for reassembly is
- missing.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>Capture Filter</command></term>
- <listitem>
- <para>
- This field allows you to specify a capture filter.
- Capture filters are discussed in more details in
- <xref linkend="ChCapCaptureFilterSection"/>. It defaults to empty, or
- no filter.
- </para>
- <para>
- You can also click on the button labelled Capture Filter, and Ethereal
- will bring up the Capture Filters dialog box and allow you to create
- and/or select a filter. Please see
- <xref linkend="ChWorkDefineFilterSection"/>
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
- <section><title>Capture File(s) frame</title>
- <para>
- An explanation about capture file usage can be found in <xref
- linkend="ChCapCaptureFiles"/>.
- </para>
- <variablelist>
- <varlistentry><term><command>File</command></term>
- <listitem>
- <para>
- This field allows you to specify the file name that will be
- used for the capture file. This field is left blank by default.
- If the field is left blank, the capture data will be stored in a
- temporary file, see <xref linkend="ChCapCaptureFiles"/> for
- details.
- </para>
- <para>
- You can also click on the button to the right of this field to
- browse through the filesystem.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>Use multiple files</command></term>
- <listitem>
- <para>
- Instead of using a single file, Ethereal will automatically switch
- to a new one, if a specific trigger condition is reached.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>Next file every n megabyte(s)</command></term>
- <listitem>
- <para>
- Multiple files only: Switch to the next file after the given
- number of byte(s)/kilobyte(s)/megabyte(s)/gigabyte(s) have been
- captured.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>Next file every n minute(s)</command></term>
- <listitem>
- <para>
- Multiple files only: Switch to the next file after the given
- number of second(s)/minutes(s)/hours(s)/days(s) have elapsed.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>Ring buffer with n files</command></term>
- <listitem>
- <para>
- Multiple files only: Form a ring buffer of the capture files, with
- the given number of files.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>Stop capture after n file(s)</command></term>
- <listitem>
- <para>
- Multiple files only: Stop capturing after switching to the next
- file the given number of times.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
- <section><title>Stop Capture... frame</title>
- <variablelist>
- <varlistentry><term><command>... after n packet(s)</command></term>
- <listitem>
- <para>
- Stop capturing after the given number of packets have been
- captured.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>... after n megabytes(s)</command></term>
- <listitem>
- <para>
- Stop capturing after the given number of
- byte(s)/kilobyte(s)/megabyte(s)/gigabyte(s) have been captured.
- This option is greyed out, if "Use multiple files" is selected.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>... after n minute(s)</command></term>
- <listitem>
- <para>
- Stop capturing after the given number of
- second(s)/minutes(s)/hours(s)/days(s) have elapsed.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
- <section><title>Display Options frame</title>
- <variablelist>
- <varlistentry>
- <term>
- <command>Update list of packets in real time</command>
- </term>
- <listitem>
- <para>
- This option allows you to specify that Ethereal
- should update the packet list pane in real time. If you
- do not specify this, Ethereal does not display any
- packets until you stop the capture. When you check this,
- Ethereal captures in a separate process
- and feeds the captures to the display process.
- </para>
- <note>
- <title>Note</title>
- <para>
- If this option is checked, it will disable the "Use multiple files"
- option.
- </para>
- </note>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <command>Automatic scrolling in live capture</command>
- </term>
- <listitem>
- <para>
- This option allows you to specify that Ethereal
- should scroll the packet list pane as new packets come
- in, so you are always looking at the last packet. If you
- do not specify this, Ethereal simply adds new packets onto
- the end of the list, but does not scroll the packet list
- pane. This option is greyed out if
- "Update list of packets in real time" is disabled.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <command>Hide capture info dialog</command>
- </term>
- <listitem>
- <para>
- If this option is checked, the following capture info dialog will be
- hidden. This option is greyed out, if "Update list of packets in real
- time" is disabled.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
- <section><title>Name Resolution frame</title>
- <variablelist>
- <varlistentry>
- <term><command>Enable MAC name resolution</command></term>
- <listitem>
- <para>
- This option allows you to control whether or not
- Ethereal translates MAC addresses into names, see
- <xref linkend="ChAdvNameResolutionSection"/>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><command>Enable network name resolution</command></term>
- <listitem>
- <para>
- This option allows you to control whether or not
- Ethereal translates network addresses into names, see
- <xref linkend="ChAdvNameResolutionSection"/>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><command>Enable transport name resolution</command></term>
- <listitem>
- <para>
- This option allows you to control whether or not
- Ethereal translates transport addresses into protocols, see
- <xref linkend="ChAdvNameResolutionSection"/>.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
- <section><title>Buttons</title>
- <para>
- Once you have set the values you desire and have selected the
- options you need, simply click on <command>OK</command> to commence the
- capture, or <command>Cancel</command> to cancel the capture.
- </para>
- <para>
- If you start a capture, Ethereal pops up a dialog box that shows you
- the progress of the capture and allows you to stop capturing when
- you have enough packets captured, see
- <xref linkend="ChCapRunningSection"/>.
- </para>
- </section>
- </section>
-
- <section id="ChCapCaptureFiles"><title>Capture files and file modes</title>
- <para>
- While capturing, the underlying libpcap capturing engine will grab the
- packets from the network card and keep the packet data in a (relatively)
- small kernel buffer. This data is read by Ethereal and saved into
- the capture file(s) the user specified.
- </para>
-
- <para>
- Different modes of operation are available when saving this packet data to
- the capture file(s).
- </para>
-
- <tip><title>Tip!</title>
- <para>
- Working with large files (several 100 MB's) can be quite slow. If you plan
- to do a long term capture or capturing from a high traffic network, think
- about using one of the "Multiple files" options. This will spread the
- captured packets over several smaller files which can be much more
- pleasant to work with.
- </para>
- </tip>
- <note><title>Note!</title>
- <para>
- Using Multiple files may cut context related information.
- Ethereal keeps context information of the loaded packet data, so it can
- report context related problems (like a stream error) and keeps information
- about context related protocols (e.g. where data is exchanged at the
- establishing phase and only referred to in later packets).
- As it keeps this information only for the loaded file, using one of
- the multiple file modes may cut these contexts, If the establishing phase
- is saved in one file and the things you would like to see is in another,
- you might not see some of the valuable context related information.
- </para>
- </note>
- <tip><title>Tip!</title>
- <para>
- Information about the folders used for the capture file(s), can be found
- in <xref linkend="AppFiles"/>.
- </para>
- </tip>
-
- <table id="ChCapTabCaptureFiles"><title>Capture file mode selected by capture options</title>
- <tgroup cols="4">
- <colspec colnum="1" colwidth="72pt"/>
- <colspec colnum="2" colwidth="80pt"/>
- <colspec colnum="3" colwidth="80pt"/>
- <thead>
- <row>
- <entry>Mode</entry>
- <entry>"File" option</entry>
- <entry>"Use multiple files" option</entry>
- <entry>"Ring buffer with n files" option</entry>
- <entry>Resulting filename(s) used</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><command>Single temporary file</command></entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>etherXXXXXX (where XXXXXX is a unique number)</entry>
- </row>
- <row>
- <entry><command>Single named file</command></entry>
- <entry>foo.cap</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>foo.cap</entry>
- </row>
- <row>
- <entry><command>Multiple files, continuous</command></entry>
- <entry>foo.cap</entry>
- <entry>x</entry>
- <entry>-</entry>
- <entry>foo_00001_20040205110102.cap, foo_00002_20040205110102.cap, ...</entry>
- </row>
- <row>
- <entry><command>Multiple files, ring buffer</command></entry>
- <entry>foo.cap</entry>
- <entry>x</entry>
- <entry>x</entry>
- <entry>foo_00001_20040205110102.cap, foo_00002_20040205110102.cap, ...</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <variablelist>
- <varlistentry>
- <term><command>Single temporary file</command></term>
- <listitem>
- <para>
- A temporary file will be created and used (this is the default). After the
- capturing is stopped, this file can be saved later under a user specified
- name.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><command>Single named file</command></term>
- <listitem>
- <para>
- A single capture file will be used. If you want to place the new capture
- file to a specific folder, choose this mode.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><command>Multiple files, continuous</command></term>
- <listitem>
- <para>
- Like the "Single named file" mode, but a new file is created and used,
- after reaching one of the multiple file switch conditions (one of the
- "Next file every ..." values).
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><command>Multiple files, ring buffer</command></term>
- <listitem>
- <para>
- Much like "Multiple files continuous", reaching one of the multiple files
- switch conditions (one of the "Next file every ..." values) will switch
- to the next file. This will be a newly created file if value of "Ring
- buffer with n files" is not reached, otherwise it will replace the oldest
- of the formerly used files (thus forming a "ring").
- </para>
- <para>
- This mode will limit the maximum disk usage, even for an unlimited amount of
- capture input data, keeping the latest captured data.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
-
- <section id="ChCapLinkLayerHeader"><title>Link-layer header type</title>
- <para>
- In the usual case, you won't have to choose this link-layer header type.
- The following paragraphs describe the exceptional cases, where
- selecting this type is possible, so you will have a guide what to do:
- </para>
- <para>
- If you are capturing on an 802.11 device on some versions of BSD, this
- might offer a choice of "Ethernet" or "802.11". "Ethernet" will cause
- the captured packets to have fake Ethernet headers; "802.11" will cause
- them to have IEEE 802.11 headers. Unless the capture needs to be read by
- an application that doesn't support 802.11 headers, you should select
- "802.11".
- </para>
- <para>
- If you are capturing on an Endace DAG card connected to a synchronous
- serial line, this might offer a choice of "PPP over serial" or
- "Cisco HDLC"; if the protocol on the serial line is PPP, select
- "PPP over serial", and if the protocol on the serial line is Cisco HDLC,
- select "Cisco HDLC".
- </para>
- <para>
- If you are capturing on an Endace DAG card connected to an ATM network,
- this might offer a choice of "RFC 1483 IP-over-ATM" or "Sun raw ATM".
- If the only traffic being captured is RFC 1483 LLC-encapsulated IP, or if
- the capture needs to be read by an application that doesn't support SunATM
- headers, select "RFC 1483 IP-over-ATM", otherwise select "Sun raw ATM".
- </para>
- <para>
- If you are capturing on an Ethernet device, this might offer a choice of
- "Ethernet" or "DOCSIS". If you are capturing traffic from a Cisco Cable
- Modem Termination System that is putting DOCSIS traffic onto the Ethernet
- to be captured, select "DOCSIS", otherwise select "Ethernet".
- </para>
- </section>
-
- <section id="ChCapCaptureFilterSection"><title>Filtering while capturing</title>
- <para>
- Ethereal uses the libpcap filter language for capture filters.
- This is explained in the tcpdump man page, which can be hard to
- understand, so it's explained here to some extent.
- </para>
- <para>
- You enter the capture filter into the Filter field of the Ethereal
- Capture Options dialog box, as shown in
- <xref linkend="ChCapCaptureOptionsDialog"/>. The following is an outline of
- the syntax of the <command>tcpdump</command> capture filter language.
- </para>
- <para>
- A capture filter takes the form of a series of primitive expressions
- connected by conjuctions (<command>and/or</command>) and optionally
- preceded by <command>not</command>:
- <programlisting>
-[not] <command>primitive</command> [and|or [not] <command>primitive</command> ...]
- </programlisting>
- An example is shown in <xref linkend="ChCapExFilt1"/>.
-
- <example id="ChCapExFilt1">
- <title>
- A capture filter for telnet than captures traffic to and from a
- particular host
- </title>
- <programlisting>
-tcp port 23 and host 10.0.0.5
- </programlisting>
- </example>
- This example captures telnet traffic to and from the host
- 10.0.0.5, and shows how to use two primitives and the
- <command>and</command> conjunction. Another example is shown in
- <xref linkend="ChCapExFilt2"/>, and shows how to capture all
- telnet traffic except that from 10.0.0.5.
- <example id="ChCapExFilt2">
- <title>
- Capturing all telnet traffic not from 10.0.0.5</title>
- <programlisting>
-tcp port 23 and not host 10.0.0.5
- </programlisting>
- </example>
- </para>
-
- <para>
- XXX - add examples to the following list.
- </para>
- <para>
- A primitive is simply one of the following:
- <variablelist>
- <varlistentry>
- <term><command>[src|dst] host <host></command></term>
- <listitem>
- <para>
- This primitive allows you to filter on a host IP
- address or name. You can optionally precede the
- primitive with the keyword <command>src|dst</command>
- to specify that you are only interested in source or
- destination addresses. If these are not present,
- packets where the specified address appears as either
- the source or the destination address will be selected.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <command>ether [src|dst] host <ehost></command>
- </term>
- <listitem>
- <para>
- This primitive allows you to filter on Ethernet host
- addresses. You can optionally include the keyword
- <command>src|dst</command> between the keywords
- <command>ether</command> and <command>host</command>
- to specify that you are only interested in source
- or destination addresses. If these are not present,
- packets where the specified address appears in either
- the source or destination address will be selected.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><command>gateway host <host></command></term>
- <listitem>
- <para>
- This primitive allows you to filter on packets that
- used <command>host</command> as a gateway. That is, where
- the Ethernet source or destination was
- <command>host</command> but neither the source nor
- destination IP address was <command>host</command>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <command>
- [src|dst] net <net> [{mask <mask>}|{len <len>}]
- </command>
- </term>
- <listitem>
- <para>
- This primitive allows you to filter on network numbers.
- You can optionally precede this primitive with the
- keyword <command>src|dst</command> to specify that you
- are only interested in a source or destination network.
- If neither of these are present, packets will be
- selected that have the specified network in either the
- source or destination address. In addition, you can
- specify either the netmask or the CIDR prefix for the
- network if they are different from your own.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <command>[tcp|udp] [src|dst] port <port></command>
- </term>
- <listitem>
- <para>
- This primitive allows you to filter on TCP and UDP port
- numbers. You can optionally precede this primitive with
- the keywords <command>src|dst</command> and
- <command>tcp|udp</command> which allow you to specify
- that you are only interested in source or destination
- ports and TCP or UDP packets respectively. The
- keywords <command>tcp|udp</command> must appear before
- <command>src|dst</command>.
- </para>
- <para>
- If these are not specified, packets will be selected
- for both the TCP and UDP protocols and when the
- specified address appears in either the source or
- destination port field.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><command>less|greater <length></command></term>
- <listitem>
- <para>
- This primitive allows you to filter on packets whose
- length was less than or equal to the specified length,
- or greater than or equal to the specified length,
- respectively.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><command>ip|ether proto <protocol></command></term>
- <listitem>
- <para>
- This primitive allows you to filter on the specified
- protocol at either the Ethernet layer or the IP layer.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><command>ether|ip broadcast|multicast</command></term>
- <listitem>
- <para>
- This primitive allows you to filter on either
- Ethernet or IP broadcasts or multicasts.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><command><expr> relop <expr></command></term>
- <listitem>
- <para>
- This primitive allows you to create complex filter
- expressions that select bytes or ranges of bytes in
- packets. Please see the tcpdump man pages for more
- details.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
- </section>
-
- <section id="ChCapRunningSection"><title>Running Capture</title>
- <para>
- While the capture is running, the following dialog box is shown:
- <figure id="ChCapCaptureInfoDialog">
- <title>The "Capture Info" dialog box</title>
- <graphic entityref="EtherealCaptureInfoDialog" format="JPG"/>
- </figure>
- This dialog box will inform you about the number of captured packets and
- the time since the capture was started. The selection which protocols
- are counted cannot be changed.
- </para>
- <tip><title>Tip!</title>
- <para>
- This Capture Info dialog box can be hidden, using the "Hide capture info
- dialog" option in the Capture Options dialog box.
- </para>
- </tip>
- <section id="ChCapStopSection"><title>Stop the running capture</title>
- <para>
- A running capture session will be stopped in one of the following ways:
- <orderedlist>
- <listitem>
- <para>Using the Stop button from the <command>Capture Info dialog box
- </command>.
- </para>
- <note><title>Note!</title>
- <para>
- The Capture Info dialog box might be hidden, if the option "Hide capture
- info dialog" is used.
- </para>
- </note>
- </listitem>
- <listitem>
- <para>Using the <command>menu item</command> "Capture/Stop Capture" or
- the corresponding Stop Capture <command>toolbar icon</command>
- <inlinegraphic entityref="EtherealToolbarStop" format="PNG"/>.
- </para>
- <note><title>Note!</title>
- <para>
- These are only available, if the option "Update list of packets in real
- time" is used.
- </para>
- </note>
- </listitem>
- <listitem>
- <para>Pressing the accelerator keys: <command>Ctrl+E</command>.
- </para>
- </listitem>
- <listitem>
- <para>The capture will be automatically stopped, if one of the
- <command>Stop Conditions</command> is exceeded, e.g. the maximum amount
- of data was captured.
- </para>
- </listitem>
- </orderedlist>
- </para>
- </section>
- </section>
-
-</chapter>
-<!-- End of EUG Chapter Capture -->
-
+<!-- EUG Chapter Capture --> +<!-- $Id$ --> + +<chapter id="ChapterCapture"> + <title>Capturing Live Network Data</title> + <section id="ChCapCapturingSection"><title>Start Capturing</title> + <para> + There are two methods you can use to start capturing packets with + Ethereal: + <orderedlist> + <listitem> + <para> + From the command line using the following: + <programlisting> +ethereal -i eth0 -k + </programlisting> + This will start Ethereal capturing on interface eth0. + </para> + </listitem> + <listitem> + <para> + By starting Ethereal and then selecting Start... from the + Capture menu (or use the corresponding item in the "Main" toolbar), + this brings up the Capture Options dialog box. + </para> + </listitem> + </orderedlist> + </para> + </section> + + <section id="ChCapCaptureOptions"> + <title>The "Capture Options" dialog box</title> + <para> + When you select Start... from the Capture menu, Ethereal pops + up the "Capture Options" dialog box as shown in + <xref linkend="ChCapCaptureOptionsDialog"/>. + </para> + <figure id="ChCapCaptureOptionsDialog"> + <title>The "Capture Options" dialog box</title> + <graphic entityref="EtherealCaptureOptionsDialog" format="JPG"/> + </figure> + <tip><title>Tip!</title> + <para> + If you are unsure which options to choose in this dialog box, just try + keeping the defaults as this should work well in many cases. + </para> + </tip> + <para> + You can set the following fields in this dialog box: + </para> + <section><title>Capture frame</title> + <variablelist> + <varlistentry><term><command>Interface</command></term> + <listitem> + <para> + This field specifies the interface you want to capture on. + You can only capture on one interface, and you can only + capture on interfaces that Ethereal has found on the + system. It is a drop-down list, so simply click on the + button on the right hand side and select the interface you + want. It defaults to the first non-loopback interface that + supports capturing, and if there are none, the first + loopback interface. On some systems, loopback interfaces + cannot be used for capturing (loopback interfaces are not available + on Windows platforms). + </para> + <para> + This field performs the same function as the + <command>-i <interface></command> command line option. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Link-layer header type</command></term> + <listitem> + <para> + Unless you are in the rare situation that you need this, just keep + the default. For a detailed description, see + <xref linkend="ChCapLinkLayerHeader"/> + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Buffer size: n megabyte(s)</command></term> + <listitem> + <para> + Enter the buffer size to be used while capturing. This is the size + of the kernel buffer which will keep the captured packets, until + they are written to disk. If you encounter packet drops, try + increasing this value. + </para> + <note> + <title>Note</title> + <para>This option is only available on Windows platforms.</para> + </note> + </listitem> + </varlistentry> + <varlistentry> + <term> + <command>Capture packets in promiscuous mode</command> + </term> + <listitem> + <para> + This checkbox allows you to specify that Ethereal + should put the interface in promiscuous mode when capturing. + If you do not specify this, Ethereal will only capture the + packets going to or from your computer (not + all packets on your LAN segment). + </para> + <note> + <title>Note</title> + <para> + If some other process has put the interface in + promiscuous mode you may be capturing in promiscuous + mode even if you turn off this option + </para> + </note> + <note> + <title>Note</title> + <para> + Even in promiscuous mode you still won't necessarily see all packets + on your LAN segment, see <ulink url="&EtherealFAQPromiscPage;"/> for + some more explanations. + </para> + </note> + </listitem> + </varlistentry> + <varlistentry><term><command>Limit each packet to n bytes</command></term> + <listitem> + <para> + This field allows you to specify the maximum amount of + data that will be captured for each packet, and is + sometimes referred to as the <command>snaplen</command>. If disabled, + the default is 65535, which will be sufficient for most + protocols. Some rules of thumb: + </para> + <itemizedlist> + <listitem> + <para> + If you are unsure, just keep the default value. + </para> + </listitem> + <listitem> + <para> + If you don't need all of the data in a packet - for example, if you + only need the link-layer, IP, and TCP headers - you might want to + choose a small snapshot length, as less CPU time is required for + copying packets, less buffer space is required for packets, and thus + perhaps fewer packets will be dropped if traffic is very heavy. + </para> + </listitem> + <listitem> + <para> + If you don't capture all of the data in a packet, you might find that + the packet data you want is in the part that's dropped, or that + reassembly isn't possible as the data required for reassembly is + missing. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry><term><command>Capture Filter</command></term> + <listitem> + <para> + This field allows you to specify a capture filter. + Capture filters are discussed in more details in + <xref linkend="ChCapCaptureFilterSection"/>. It defaults to empty, or + no filter. + </para> + <para> + You can also click on the button labelled Capture Filter, and Ethereal + will bring up the Capture Filters dialog box and allow you to create + and/or select a filter. Please see + <xref linkend="ChWorkDefineFilterSection"/> + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section><title>Capture File(s) frame</title> + <para> + An explanation about capture file usage can be found in <xref + linkend="ChCapCaptureFiles"/>. + </para> + <variablelist> + <varlistentry><term><command>File</command></term> + <listitem> + <para> + This field allows you to specify the file name that will be + used for the capture file. This field is left blank by default. + If the field is left blank, the capture data will be stored in a + temporary file, see <xref linkend="ChCapCaptureFiles"/> for + details. + </para> + <para> + You can also click on the button to the right of this field to + browse through the filesystem. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Use multiple files</command></term> + <listitem> + <para> + Instead of using a single file, Ethereal will automatically switch + to a new one, if a specific trigger condition is reached. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Next file every n megabyte(s)</command></term> + <listitem> + <para> + Multiple files only: Switch to the next file after the given + number of byte(s)/kilobyte(s)/megabyte(s)/gigabyte(s) have been + captured. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Next file every n minute(s)</command></term> + <listitem> + <para> + Multiple files only: Switch to the next file after the given + number of second(s)/minutes(s)/hours(s)/days(s) have elapsed. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Ring buffer with n files</command></term> + <listitem> + <para> + Multiple files only: Form a ring buffer of the capture files, with + the given number of files. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Stop capture after n file(s)</command></term> + <listitem> + <para> + Multiple files only: Stop capturing after switching to the next + file the given number of times. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section><title>Stop Capture... frame</title> + <variablelist> + <varlistentry><term><command>... after n packet(s)</command></term> + <listitem> + <para> + Stop capturing after the given number of packets have been + captured. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>... after n megabytes(s)</command></term> + <listitem> + <para> + Stop capturing after the given number of + byte(s)/kilobyte(s)/megabyte(s)/gigabyte(s) have been captured. + This option is greyed out, if "Use multiple files" is selected. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>... after n minute(s)</command></term> + <listitem> + <para> + Stop capturing after the given number of + second(s)/minutes(s)/hours(s)/days(s) have elapsed. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section><title>Display Options frame</title> + <variablelist> + <varlistentry> + <term> + <command>Update list of packets in real time</command> + </term> + <listitem> + <para> + This option allows you to specify that Ethereal + should update the packet list pane in real time. If you + do not specify this, Ethereal does not display any + packets until you stop the capture. When you check this, + Ethereal captures in a separate process + and feeds the captures to the display process. + </para> + <note> + <title>Note</title> + <para> + If this option is checked, it will disable the "Use multiple files" + option. + </para> + </note> + </listitem> + </varlistentry> + <varlistentry> + <term> + <command>Automatic scrolling in live capture</command> + </term> + <listitem> + <para> + This option allows you to specify that Ethereal + should scroll the packet list pane as new packets come + in, so you are always looking at the last packet. If you + do not specify this, Ethereal simply adds new packets onto + the end of the list, but does not scroll the packet list + pane. This option is greyed out if + "Update list of packets in real time" is disabled. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <command>Hide capture info dialog</command> + </term> + <listitem> + <para> + If this option is checked, the following capture info dialog will be + hidden. This option is greyed out, if "Update list of packets in real + time" is disabled. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section><title>Name Resolution frame</title> + <variablelist> + <varlistentry> + <term><command>Enable MAC name resolution</command></term> + <listitem> + <para> + This option allows you to control whether or not + Ethereal translates MAC addresses into names, see + <xref linkend="ChAdvNameResolutionSection"/>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command>Enable network name resolution</command></term> + <listitem> + <para> + This option allows you to control whether or not + Ethereal translates network addresses into names, see + <xref linkend="ChAdvNameResolutionSection"/>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command>Enable transport name resolution</command></term> + <listitem> + <para> + This option allows you to control whether or not + Ethereal translates transport addresses into protocols, see + <xref linkend="ChAdvNameResolutionSection"/>. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section><title>Buttons</title> + <para> + Once you have set the values you desire and have selected the + options you need, simply click on <command>OK</command> to commence the + capture, or <command>Cancel</command> to cancel the capture. + </para> + <para> + If you start a capture, Ethereal pops up a dialog box that shows you + the progress of the capture and allows you to stop capturing when + you have enough packets captured, see + <xref linkend="ChCapRunningSection"/>. + </para> + </section> + </section> + + <section id="ChCapCaptureFiles"><title>Capture files and file modes</title> + <para> + While capturing, the underlying libpcap capturing engine will grab the + packets from the network card and keep the packet data in a (relatively) + small kernel buffer. This data is read by Ethereal and saved into + the capture file(s) the user specified. + </para> + + <para> + Different modes of operation are available when saving this packet data to + the capture file(s). + </para> + + <tip><title>Tip!</title> + <para> + Working with large files (several 100 MB's) can be quite slow. If you plan + to do a long term capture or capturing from a high traffic network, think + about using one of the "Multiple files" options. This will spread the + captured packets over several smaller files which can be much more + pleasant to work with. + </para> + </tip> + <note><title>Note!</title> + <para> + Using Multiple files may cut context related information. + Ethereal keeps context information of the loaded packet data, so it can + report context related problems (like a stream error) and keeps information + about context related protocols (e.g. where data is exchanged at the + establishing phase and only referred to in later packets). + As it keeps this information only for the loaded file, using one of + the multiple file modes may cut these contexts, If the establishing phase + is saved in one file and the things you would like to see is in another, + you might not see some of the valuable context related information. + </para> + </note> + <tip><title>Tip!</title> + <para> + Information about the folders used for the capture file(s), can be found + in <xref linkend="AppFiles"/>. + </para> + </tip> + + <table id="ChCapTabCaptureFiles"><title>Capture file mode selected by capture options</title> + <tgroup cols="4"> + <colspec colnum="1" colwidth="72pt"/> + <colspec colnum="2" colwidth="80pt"/> + <colspec colnum="3" colwidth="80pt"/> + <thead> + <row> + <entry>Mode</entry> + <entry>"File" option</entry> + <entry>"Use multiple files" option</entry> + <entry>"Ring buffer with n files" option</entry> + <entry>Resulting filename(s) used</entry> + </row> + </thead> + <tbody> + <row> + <entry><command>Single temporary file</command></entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>etherXXXXXX (where XXXXXX is a unique number)</entry> + </row> + <row> + <entry><command>Single named file</command></entry> + <entry>foo.cap</entry> + <entry>-</entry> + <entry>-</entry> + <entry>foo.cap</entry> + </row> + <row> + <entry><command>Multiple files, continuous</command></entry> + <entry>foo.cap</entry> + <entry>x</entry> + <entry>-</entry> + <entry>foo_00001_20040205110102.cap, foo_00002_20040205110102.cap, ...</entry> + </row> + <row> + <entry><command>Multiple files, ring buffer</command></entry> + <entry>foo.cap</entry> + <entry>x</entry> + <entry>x</entry> + <entry>foo_00001_20040205110102.cap, foo_00002_20040205110102.cap, ...</entry> + </row> + </tbody> + </tgroup> + </table> + <variablelist> + <varlistentry> + <term><command>Single temporary file</command></term> + <listitem> + <para> + A temporary file will be created and used (this is the default). After the + capturing is stopped, this file can be saved later under a user specified + name. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command>Single named file</command></term> + <listitem> + <para> + A single capture file will be used. If you want to place the new capture + file to a specific folder, choose this mode. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command>Multiple files, continuous</command></term> + <listitem> + <para> + Like the "Single named file" mode, but a new file is created and used, + after reaching one of the multiple file switch conditions (one of the + "Next file every ..." values). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command>Multiple files, ring buffer</command></term> + <listitem> + <para> + Much like "Multiple files continuous", reaching one of the multiple files + switch conditions (one of the "Next file every ..." values) will switch + to the next file. This will be a newly created file if value of "Ring + buffer with n files" is not reached, otherwise it will replace the oldest + of the formerly used files (thus forming a "ring"). + </para> + <para> + This mode will limit the maximum disk usage, even for an unlimited amount of + capture input data, keeping the latest captured data. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + + <section id="ChCapLinkLayerHeader"><title>Link-layer header type</title> + <para> + In the usual case, you won't have to choose this link-layer header type. + The following paragraphs describe the exceptional cases, where + selecting this type is possible, so you will have a guide what to do: + </para> + <para> + If you are capturing on an 802.11 device on some versions of BSD, this + might offer a choice of "Ethernet" or "802.11". "Ethernet" will cause + the captured packets to have fake Ethernet headers; "802.11" will cause + them to have IEEE 802.11 headers. Unless the capture needs to be read by + an application that doesn't support 802.11 headers, you should select + "802.11". + </para> + <para> + If you are capturing on an Endace DAG card connected to a synchronous + serial line, this might offer a choice of "PPP over serial" or + "Cisco HDLC"; if the protocol on the serial line is PPP, select + "PPP over serial", and if the protocol on the serial line is Cisco HDLC, + select "Cisco HDLC". + </para> + <para> + If you are capturing on an Endace DAG card connected to an ATM network, + this might offer a choice of "RFC 1483 IP-over-ATM" or "Sun raw ATM". + If the only traffic being captured is RFC 1483 LLC-encapsulated IP, or if + the capture needs to be read by an application that doesn't support SunATM + headers, select "RFC 1483 IP-over-ATM", otherwise select "Sun raw ATM". + </para> + <para> + If you are capturing on an Ethernet device, this might offer a choice of + "Ethernet" or "DOCSIS". If you are capturing traffic from a Cisco Cable + Modem Termination System that is putting DOCSIS traffic onto the Ethernet + to be captured, select "DOCSIS", otherwise select "Ethernet". + </para> + </section> + + <section id="ChCapCaptureFilterSection"><title>Filtering while capturing</title> + <para> + Ethereal uses the libpcap filter language for capture filters. + This is explained in the tcpdump man page, which can be hard to + understand, so it's explained here to some extent. + </para> + <para> + You enter the capture filter into the Filter field of the Ethereal + Capture Options dialog box, as shown in + <xref linkend="ChCapCaptureOptionsDialog"/>. The following is an outline of + the syntax of the <command>tcpdump</command> capture filter language. + </para> + <para> + A capture filter takes the form of a series of primitive expressions + connected by conjuctions (<command>and/or</command>) and optionally + preceded by <command>not</command>: + <programlisting> +[not] <command>primitive</command> [and|or [not] <command>primitive</command> ...] + </programlisting> + An example is shown in <xref linkend="ChCapExFilt1"/>. + + <example id="ChCapExFilt1"> + <title> + A capture filter for telnet than captures traffic to and from a + particular host + </title> + <programlisting> +tcp port 23 and host 10.0.0.5 + </programlisting> + </example> + This example captures telnet traffic to and from the host + 10.0.0.5, and shows how to use two primitives and the + <command>and</command> conjunction. Another example is shown in + <xref linkend="ChCapExFilt2"/>, and shows how to capture all + telnet traffic except that from 10.0.0.5. + <example id="ChCapExFilt2"> + <title> + Capturing all telnet traffic not from 10.0.0.5</title> + <programlisting> +tcp port 23 and not host 10.0.0.5 + </programlisting> + </example> + </para> + + <para> + XXX - add examples to the following list. + </para> + <para> + A primitive is simply one of the following: + <variablelist> + <varlistentry> + <term><command>[src|dst] host <host></command></term> + <listitem> + <para> + This primitive allows you to filter on a host IP + address or name. You can optionally precede the + primitive with the keyword <command>src|dst</command> + to specify that you are only interested in source or + destination addresses. If these are not present, + packets where the specified address appears as either + the source or the destination address will be selected. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <command>ether [src|dst] host <ehost></command> + </term> + <listitem> + <para> + This primitive allows you to filter on Ethernet host + addresses. You can optionally include the keyword + <command>src|dst</command> between the keywords + <command>ether</command> and <command>host</command> + to specify that you are only interested in source + or destination addresses. If these are not present, + packets where the specified address appears in either + the source or destination address will be selected. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command>gateway host <host></command></term> + <listitem> + <para> + This primitive allows you to filter on packets that + used <command>host</command> as a gateway. That is, where + the Ethernet source or destination was + <command>host</command> but neither the source nor + destination IP address was <command>host</command>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <command> + [src|dst] net <net> [{mask <mask>}|{len <len>}] + </command> + </term> + <listitem> + <para> + This primitive allows you to filter on network numbers. + You can optionally precede this primitive with the + keyword <command>src|dst</command> to specify that you + are only interested in a source or destination network. + If neither of these are present, packets will be + selected that have the specified network in either the + source or destination address. In addition, you can + specify either the netmask or the CIDR prefix for the + network if they are different from your own. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <command>[tcp|udp] [src|dst] port <port></command> + </term> + <listitem> + <para> + This primitive allows you to filter on TCP and UDP port + numbers. You can optionally precede this primitive with + the keywords <command>src|dst</command> and + <command>tcp|udp</command> which allow you to specify + that you are only interested in source or destination + ports and TCP or UDP packets respectively. The + keywords <command>tcp|udp</command> must appear before + <command>src|dst</command>. + </para> + <para> + If these are not specified, packets will be selected + for both the TCP and UDP protocols and when the + specified address appears in either the source or + destination port field. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command>less|greater <length></command></term> + <listitem> + <para> + This primitive allows you to filter on packets whose + length was less than or equal to the specified length, + or greater than or equal to the specified length, + respectively. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command>ip|ether proto <protocol></command></term> + <listitem> + <para> + This primitive allows you to filter on the specified + protocol at either the Ethernet layer or the IP layer. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command>ether|ip broadcast|multicast</command></term> + <listitem> + <para> + This primitive allows you to filter on either + Ethernet or IP broadcasts or multicasts. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command><expr> relop <expr></command></term> + <listitem> + <para> + This primitive allows you to create complex filter + expressions that select bytes or ranges of bytes in + packets. Please see the tcpdump man pages for more + details. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </section> + + <section id="ChCapRunningSection"><title>Running Capture</title> + <para> + While the capture is running, the following dialog box is shown: + <figure id="ChCapCaptureInfoDialog"> + <title>The "Capture Info" dialog box</title> + <graphic entityref="EtherealCaptureInfoDialog" format="JPG"/> + </figure> + This dialog box will inform you about the number of captured packets and + the time since the capture was started. The selection which protocols + are counted cannot be changed. + </para> + <tip><title>Tip!</title> + <para> + This Capture Info dialog box can be hidden, using the "Hide capture info + dialog" option in the Capture Options dialog box. + </para> + </tip> + <section id="ChCapStopSection"><title>Stop the running capture</title> + <para> + A running capture session will be stopped in one of the following ways: + <orderedlist> + <listitem> + <para>Using the Stop button from the <command>Capture Info dialog box + </command>. + </para> + <note><title>Note!</title> + <para> + The Capture Info dialog box might be hidden, if the option "Hide capture + info dialog" is used. + </para> + </note> + </listitem> + <listitem> + <para>Using the <command>menu item</command> "Capture/Stop Capture" or + the corresponding Stop Capture <command>toolbar icon</command> + <inlinegraphic entityref="EtherealToolbarStop" format="PNG"/>. + </para> + <note><title>Note!</title> + <para> + These are only available, if the option "Update list of packets in real + time" is used. + </para> + </note> + </listitem> + <listitem> + <para>Pressing the accelerator keys: <command>Ctrl+E</command>. + </para> + </listitem> + <listitem> + <para>The capture will be automatically stopped, if one of the + <command>Stop Conditions</command> is exceeded, e.g. the maximum amount + of data was captured. + </para> + </listitem> + </orderedlist> + </para> + </section> + </section> + +</chapter> +<!-- End of EUG Chapter Capture --> + diff --git a/docbook/ug-src/EUG_chapter_customize.xml b/docbook/ug-src/EUG_chapter_customize.xml index 3e6a7ab5bf..a14f4b1ec2 100644 --- a/docbook/ug-src/EUG_chapter_customize.xml +++ b/docbook/ug-src/EUG_chapter_customize.xml @@ -1,822 +1,824 @@ -<!-- EUG Chapter Customizing -->
-<chapter id="ChapterCustomize">
- <title>Customizing Ethereal</title>
-
- <section id="ChCustIntroduction"><title>Introduction</title>
- <para>
- Ethereal's default behaviour will usually suit your needs pretty well.
- However, as you become more familiar with Ethereal, it can be customized
- in various ways to suit your needs even better. In this chapter we explore:
- <itemizedlist>
- <listitem>
- <para>
- How to start Ethereal with command line parameters
- </para>
- </listitem>
- <listitem>
- <para>
- How to colorize the <application>Ethereal</application> display
- </para>
- </listitem>
- <listitem>
- <para>
- How to use the various preference settings
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </section>
-
- <section id="ChCustCommandLine"><title>Start Ethereal from the command line</title>
- <para>
- You can start <application>Ethereal</application> from the command
- line, but it can also be started from most Window managers
- as well. In this section we will look at starting it from the command
- line.
- </para>
- <para>
- <application>Ethereal</application> supports a large number of
- command line parameters. To see what they are, simply enter the
- command <command> ethereal -h</command> and the help information
- shown in <xref linkend="ChCustEx1"/> (or something similar) should be
- printed.
- <example id="ChCustEx1">
- <title>Help information available from Ethereal</title>
- <programlisting>
-This is GNU ethereal 0.10.5
-Compiled with GTK+ 2.4.3, with GLib 2.4.2, with WinPcap (version unknown),
-with libz 1.2.1, with libpcre 4.4, with Net-SNMP 5.1, with ADNS.
-
-Running with WinPcap version 3.0 (packet.dll version 3, 1, 0, 20), based
-on libpcap version 0.8 on Windows XP Service Pack 1, build 2600.
-
-ethereal [ -vh ] [ -klLnpQS ] [ -a <capture autostop condition> ] ...
- [ -b <number of ringbuffer files>[:<duration>] ]
- [ -B <byte view height> ] [ -c <count> ] [ -f <capture filter> ]
- [ -i <interface> ] [ -m <medium font> ] [ -N <resolving> ]
- [ -o <preference setting> ] ... [ -P <packet list height> ]
- [ -r <infile> ] [ -R <read filter> ] [ -s <snaplen> ]
- [ -t <time stamp format> ] [ -T <tree view height> ]
- [ -w <savefile> ] [ -y <link type> ] [ -z <statistics string> ]
- [ <infile> ]
- </programlisting>
- </example>
-
- We will examine each of the command line options in turn.
- </para>
- <para>
- The first thing to notice is that issuing the command
- <command>ethereal</command> by itself will bring up
- <application>Ethereal</application>.
- However, you can include as many of the command line parameters as
- you like. Their meanings are as follows ( in alphabetical order ):
- XXX - is the alphabetical order a good choice? Maybe better task based?
- <variablelist>
- <varlistentry><term><command>-a <capture autostop condition></command></term>
- <listitem>
- <para>
- Specify a criterion that specifies when Ethereal is to stop writing
- to a capture file. The criterion is of the form test:value, where test
- is one of:
- <variablelist>
- <varlistentry><term><command>duration</command></term>
- <listitem><para>
- Stop writing to a capture file after value of seconds have elapsed.
- </para></listitem>
- </varlistentry>
- <varlistentry><term><command>filesize</command></term>
- <listitem><para>
- Stop writing to a capture file after it reaches a size of value
- kilobytes (where a kilobyte is 1000 bytes, not 1024 bytes).
- </para></listitem>
- </varlistentry>
- </variablelist>
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>-b <number of ringbuffer files></command></term>
- <listitem>
- <para>
- If a maximum capture file size was specified, cause Ethereal to run
- in "ring buffer" mode, with the specified number of files. In "ring
- buffer" mode, Ethereal will write to several capture files. Their
- name is based on the number of the file and on the creation date and
- time.
- </para>
- <para>
- When the first capture file fills up, Ethereal will switch to writing
- to the next file, until it fills up the last file, at which point
- it'll discard the data in the first file (unless 0 is specified, in
- which case, the number of files is unlimited) and start writing to
- that file and so on.
- </para>
- <para>
- If the optional duration is specified, Ethereal will switch also to
- the next file when the specified number of seconds has elapsed even
- if the current file is not completely fills up.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>-B <byte view height></command></term>
- <listitem>
- <para>
- This option sets the initial height of the "Packet Bytes" pane.
- This pane is usually the bottom pane in the Ethereal display.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>-c <count></command></term>
- <listitem>
- <para>
- This option specifies the maximum number of packets to capture
- when capturing live data. It would be used in conjunction
- with the <command>-k</command> option.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>-f <capture filter></command></term>
- <listitem>
- <para>
- This option sets the initial capture filter expression to
- be used when capturing packets.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>-h</command></term>
- <listitem>
- <para>
- The <command>-h</command> option requests Ethereal to print
- its version and usage instructions (as shown above) and exit.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>-i <interface></command></term>
- <listitem>
- <para>
- The <command>-i</command> option allows you to specify,
- from the command line, which interface packet capture should
- occur on if capturing packets.
- </para>
- <para>
- An example would be: <command>ethereal -i eth0</command>.
- </para>
- <para>
- To get a listing of all the interfaces you can capture on,
- use the command <command>ifconfig -a</command> or
- <command>netstat -i</command>. Unfortunately, some versions of
- UNIX do not support <command>ifconfig -a</command>, so you
- will have to use <command>netstat -i</command> in these cases.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>-k</command></term>
- <listitem>
- <para>
- The <command>-k</command> option specifies that Ethereal
- should start capturing packets immediately. This option
- requires the use of the <command>-i</command> parameter to
- specify the interface that packet capture will occur from.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>-l</command></term>
- <listitem>
- <para>
- This option turns on automatic scrolling if the packet
- list pane is being updated automatically as packets arrive
- during a capture ( as specified by the <command>-S</command>
- flag).
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>-L</command></term>
- <listitem>
- <para>
- List the data link types supported by the interface and exit.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>-m <medium font></command></term>
- <listitem>
- <para>
- This option sets the name of the font used for most text
- displayed by Ethereal. XXX - add an example!
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>-n</command></term>
- <listitem>
- <para>
- Disable network object name resolution (such as hostname, TCP and UDP
- port names).
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>-N <resolving></command></term>
- <listitem>
- <para>
- Turns on name resolving for particular types of addresses
- and port numbers; the argument is a string that may contain
- the letters <command>m</command> to enable MAC address
- resolution, <command>n</command> to enable network address
- resolution, and <command>t</command> to enable transport-layer
- port number resolution. This overrides <command>-n</command>
- if both <command>-N</command> and <command>-n</command> are
- present. The letter C enables concurrent (asynchronous) DNS lookups.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><command>-o <preference settings></command></term>
- <listitem>
- <para>
- Sets a preference value, overriding the default value and
- any value read from a preference file. The argument to the
- flag is a string of the form prefname:value, where prefname
- is the name of the preference (which is the same name that
- would appear in the preference file), and value is the value
- to which it should be set. Multiple instances of
- <command>-o <preference settings> </command> can be
- given on a single command line.
- </para>
- <para>An example of setting a single preference would be: </para>
- <para>
- <command>
- ethereal -o mgcp.display_dissect_tree:TRUE
- </command>
- </para>
- <para>
- An example of setting multiple preferences would be:
- </para>
- <para>
- <command>
- ethereal -o mgcp.display_dissect_tree:TRUE -o mgcp.udp.callagent_port:2627
- </command>
- </para>
- <tip><title>Tip!</title>
- <para>
- You can get a list of all available preference strings from the
- preferences file, see <xref linkend="AppFiles"/>.
- </para>
- </tip>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>-p</command></term>
- <listitem>
- <para>
- Don't put the interface into promiscuous mode. Note that
- the interface might be in promiscuous mode for some other
- reason; hence, -p cannot be used to ensure that the only
- traffic that is captured is traffic sent to or from the
- machine on which Ethereal is running, broadcast traffic, and
- multicast traffic to addresses received by that machine.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><command>-P <packet list height></command></term>
- <listitem>
- <para>
- This option sets the initial height of the "Packet List" pane,
- ie, the top pane.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>-Q</command></term>
- <listitem>
- <para>
- This option forces Ethereal to exit when capturing is
- complete. It can be used with the <command>-c</command> option.
- It must be used in conjunction with the
- <command>-i</command> and <command>-w</command> options.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>-r <infile></command></term>
- <listitem>
- <para>
- This option provides the name of a capture file for Ethereal
- to read and display. This capture file can be in one of the
- formats Ethereal understands.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>-R <read filter></command></term>
- <listitem>
- <para>
- This option specifies a display filter to be applied when
- reading packets from a capture file. The syntax of this
- filter is that of the display filters discussed in
- <xref linkend="ChWorkDisplayFilterSection"/>. Packets not
- matching the filter are discarded.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>-s <snaplen></command></term>
- <listitem>
- <para>
- This option specifies the snapshot length to use when
- capturing packets. Ethereal will only capture
- <command><snaplen></command> bytes of data for each packet.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>-S</command></term>
- <listitem>
- <para>
- This option specifies that Ethereal will display packets as
- it captures them. This is done by capturing in one process
- and displaying them in a separate process. This is the same
- as "Update list of packets in real time" in the Capture Options
- dialog box.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><command>-t <time stamp format></command></term>
- <listitem>
- <para>
- This option sets the format of packet timestamps that are
- displayed in the packet list window. The format can be one of:
- <itemizedlist>
- <listitem>
- <para>
- <command>r</command> relative, which specifies timestamps are
- displayed relative to the first packet captured.
- </para>
- </listitem>
- <listitem>
- <para>
- <command>a</command> absolute, which specifies that actual times
- be displayed for all packets.
- </para>
- </listitem>
- <listitem>
- <para>
- <command>ad</command> absolute with date, which specifies that
- actual dates and times be displayed for all packets.
- </para>
- </listitem>
- <listitem>
- <para>
- <command>d</command> delta, which specifies that timestamps
- are relative to the previous packet.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><command>-T <tree view height></command></term>
- <listitem>
- <para>
- This option sets the initial height of the "Packet Details" pane.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>-v</command></term>
- <listitem>
- <para>
- The <command>-v</command> option requests
- Ethereal to print out its version information and exit.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>-w <savefile></command></term>
- <listitem>
- <para>
- This option sets the name of the <command>savefile</command>
- to be used when saving a capture file.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>-y <link type></command></term>
- <listitem>
- <para>
- If a capture is started from the command line with -k, set the data
- link type to use while capturing packets. The values reported by -L
- are the values that can be used.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>-z <statistics-string></command></term>
- <listitem>
- <para>
- Get Ethereal to collect various types of statistics and display the
- result in a window that updates in semi-real time.
- XXX - add more details here!
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
- </section>
-
- <section id="ChCustColorizationSection"><title>Packet colorization</title>
- <para>
- A very useful mechanism available in Ethereal is packet colorization.
- You can set Ethereal up so that it colorizes packets according to a
- filter. This allows you to emphasize the packets you are interested in.
- </para>
- <para>
- To colorize packets, select the Coloring Rules... menu item from
- the View menu, and Ethereal will pop up the "Coloring Rules"
- dialog box as shown in <xref linkend="ChCustColoringRulesDialog"/>.
- </para>
- <figure id="ChCustColoringRulesDialog">
- <title>The "Coloring Rules" dialog box</title>
- <graphic entityref="EtherealColoringRulesDialog" format="PNG"/>
- </figure>
- <para>
- Once the Coloring Rules dialog box is up, there are a number
- of buttons you can use, depending on whether or not you have any
- color filters installed already.
- </para>
- <note><title>Note!</title>
- <para>
- You will need to carefully select the order that rules are listed
- (and thus applied) as they are applied in order from top to bottom.
- So, more specific rules need to be listed before more general rules.
- For example, if you have a color rule for UDP before the one for DNS,
- the color rule for DNS will never be applied (as DNS uses UDP, so the
- UDP rule will be matching first).
- </para>
- </note>
- <para>
- If this is the first time you have used Coloring Rules, click on the New
- button which will bring up the Edit color filter dialog box as shown in
- <xref linkend="ChCustEditColorDialog"/>.
- </para>
- <figure id="ChCustEditColorDialog">
- <title>The "Edit Color Filter" dialog box</title>
- <graphic entityref="EtherealEditColorDialog" format="PNG"/>
- </figure>
- <para>
- In the Edit Color dialog box, simply enter a name for the color filter,
- and enter a filter string in the Filter text field.
- <xref linkend="ChCustEditColorDialog"/> shows the values
- <command>arp</command> and <command>arp</command> which means that
- the name of the color filter is <command>arp</command> and the filter
- will select protocols of type <command>arp</command>. Once you have
- entered these values, you can choose a foreground and background
- color for packets that match the filter expression. Click on
- <command>Foreground color...</command> or
- <command>Background color...</command> to achieve this and
- Ethereal will pop up the Choose foreground/background color for
- protocol dialog box as shown in
- <xref linkend="ChCustChooseColorDialog"/>.
- </para>
- <figure id="ChCustChooseColorDialog">
- <title>The "Choose color" dialog box</title>
- <graphic entityref="EtherealChooseColorDialog" format="PNG"/>
- </figure>
- <para>
- Select the color you desire for the selected packets and click on OK.
- </para>
- <note>
- <title>Note!</title>
- <para>
- You must select a color in the colorbar next to the colorwheel to
- load values into the RGB values. Alternatively, you can set the
- values to select the color you want.
- </para>
- </note>
- <para>
- <xref linkend="ChCustColorFilterMany"/> shows an example of several color
- filters being used in Ethereal. You may not like the color choices,
- however, feel free to choose your own.
- </para>
- <figure id="ChCustColorFilterMany">
- <title>Using color filters with Ethereal</title>
- <graphic entityref="EtherealThreePane1" format="PNG"/>
- </figure>
- </section>
-
- <section id="ChAdvProtocolDissectionSection">
- <title>Control Protocol dissection</title>
- <para>
- There are some ways, to let the user control how protocols are
- dissected.
- </para>
- <para>
- Each protocol has its own dissector, so dissecting a packet will
- typically involve several dissectors. As Ethereal tries to find the
- right dissector for each packet (using static "routes" and heuristics
- "guessing"), it might choose the wrong dissector in your specific
- case. For example, Ethereal won't know if you use a common protocol
- on an uncommon TCP port, e.g. using HTTP on TCP port 800 instead of
- the standard port 80.
- </para>
- <para>
- There are two ways to control the relations between protocol
- dissectors: disable a protocol dissector completely or temporarily
- divert the way Ethereal calls the dissectors.
- </para>
- <section id="ChAdvEnabledProtocols"><title>The "Enabled Protocols" dialog
- box</title>
- <para>
- The Enabled Protocols dialog box lets you enable or
- disable specific protocols, all protocols are enabled by default.
- When a protocol is disabled, Ethereal stops processing a packet
- whenever that protocol is encountered.
- </para>
- <note><title>Note!</title>
- <para>
- Disabling a protocol will prevent information about higher-layer
- protocols from being displayed. For example,
- suppose you disabled the IP protocol and selected
- a packet containing Ethernet, IP, TCP, and HTTP
- information. The Ethernet information would be
- displayed, but the IP, TCP and HTTP information
- would not - disabling IP would prevent it and
- the other protocols from being displayed.
- </para>
- </note>
- <figure id="ChAdvEnabledProtocolsFig">
- <title>The "Enabled Protocols" dialog box</title>
- <graphic entityref="EtherealEnabledProtocols" format="PNG"/>
- </figure>
- <para>
- To disable or enable a protocol, simply click on it using the
- mouse or press the space bar when the protocol is highlighted.
- </para>
- <warning><title>Warning!</title>
- <para>
- You have to use the Save button to save your settings. The OK or Apply
- buttons will not save your changes, so they will be lost when Ethereal
- is closed.
- </para>
- </warning>
- <para>
- You can choose from the following actions:
- <orderedlist>
- <listitem>
- <para>
- <command>Enable All</command> Enable all protocols in the list.
- </para>
- </listitem>
- <listitem>
- <para>
- <command>Disable All</command> Disable all protocols in the list.
- </para>
- </listitem>
- <listitem>
- <para>
- <command>Invert</command> Toggle the state of all protocols in the
- list.
- </para>
- </listitem>
- <listitem>
- <para>
- <command>OK</command> Apply the changes and close the dialog box.
- </para>
- </listitem>
- <listitem>
- <para>
- <command>Apply</command> Apply the changes and keep the dialog box
- open.
- </para>
- </listitem>
- <listitem>
- <para>
- <command>Save</command> Save the settings to the disabled_protos, see
- <xref linkend="AppFiles"/> for details.
- </para>
- </listitem>
- <listitem>
- <para>
- <command>Cancel</command> Cancel the changes and close the dialog box.
- </para>
- </listitem>
- </orderedlist>
- </para>
- </section>
-
- <section id="ChAdvDecodeAs"><title>User Specified Decodes</title>
- <para>
- The "Decode As" functionality let you temporarily divert specific
- protocol dissections. This might be useful for example, if you do some
- uncommon things on your network.
- </para>
- <para>
- <figure id="ChAdvDecodeAsFig">
- <title>The "Decode As" dialog box</title>
- <graphic scale="100" entityref="EtherealDecodeAs" format="PNG"/>
- </figure>
- The content of this dialog box depends on the selected packet when it
- was opened.
- <warning><title>Warning!</title>
- <para>
- The user specified decodes can not be saved. If you quit Ethereal,
- these settings will be lost.
- </para>
- </warning>
- <orderedlist>
- <listitem>
- <para>
- <command>Decode</command> Decode packets the selected way.
- </para>
- </listitem>
- <listitem>
- <para>
- <command>Do not decode</command> Do not decode packets the selected
- way.
- </para>
- </listitem>
- <listitem>
- <para>
- <command>Link/Network/Transport</command> Specify the way to decode
- packets. Which of these pages are available, depends on the content
- of the selected packet when this dialog box was opened.
- </para>
- </listitem>
- <listitem>
- <para>
- <command>Show Current</command> Open a dialog box showing the
- current list of user specified decodes.
- </para>
- </listitem>
- <listitem>
- <para>
- <command>OK</command> Apply the currently selected decode and close
- the dialog box.
- </para>
- </listitem>
- <listitem>
- <para>
- <command>Apply</command> Apply the currently selected decode and keep
- the dialog box open.
- </para>
- </listitem>
- <listitem>
- <para>
- <command>Cancel</command> Cancel the changes and close the dialog box.
- </para>
- </listitem>
- </orderedlist>
- </para>
- </section>
-
- <section id="ChAdvDecodeAsShow"><title>Show User Specified Decodes</title>
- <para>
- This dialog box shows the currently active user specified decodes.
- <figure id="ChAdvDecodeAsShowFig">
- <title>The "Decode As: Show" dialog box</title>
- <graphic entityref="EtherealDecodeAsShow" format="PNG"/>
- </figure>
- <orderedlist>
- <listitem>
- <para>
- <command>OK</command> Close this dialog box.
- </para>
- </listitem>
- <listitem>
- <para>
- <command>Clear</command> Removes all user specified decodes.
- </para>
- </listitem>
- </orderedlist>
- </para>
- </section>
- </section>
-
- <section id="ChCustPreferencesSection"><title>Preferences</title>
- <para>
- There are a number of preferences you can set. Simply
- select the Preferences... menu item from the Edit menu, and Ethereal
- will pop up the Preferences dialog box as shown in
- <xref linkend="ChCustGUIPrefPage"/>, with the "User Interface" page as
- default. On the left side is a tree where you can select the page to be
- shown. XXX - add detailed descriptions of all the preferences pages.
- <warning>
- <title>Warning!</title>
- <para>
- The OK or Apply button will not save the preference settings,
- you'll have to save the settings by clicking the Save button.
- </para>
- </warning>
- <itemizedlist>
- <listitem>
- <para>
- The <command>OK</command> button will apply the preferences
- settings and close the dialog.
- </para>
- </listitem>
- <listitem>
- <para>
- The <command>Apply</command> button will apply the preferences
- settings and keep the dialog open.
- </para>
- </listitem>
- <listitem>
- <para>
- The <command>Save</command> button will apply the preferences
- settings, save the settings on the harddisk and keep the dialog open.
- </para>
- </listitem>
- <listitem>
- <para>
- The <command>Cancel</command> button will restore all preferences
- settings to the last saved state.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <section><title>The "User Interface" page</title>
- <figure id="ChCustGUIPrefPage">
- <title>The "User Interface" preferences page</title>
- <graphic entityref="EtherealGUIPreferences" format="PNG"/>
- </figure>
- <para>
- This page allows you to configure various characteristics
- of the GUI.
- </para>
- </section>
- <section><title>The "User Interface: Layout" page</title>
- <figure id="ChCustGUILayoutPrefPage">
- <title>The "User Interface: Layout" preferences page</title>
- <graphic entityref="EtherealGUILayoutPreferences" format="PNG"/>
- </figure>
- <para>
- This page selects the GUI layout of the main window.
- </para>
- </section>
- <section><title>The "User Interface: Columns" page</title>
- <para>
- <figure id="ChCustGUIColumnsPrefPage">
- <title>The "User Interface: Columns" preferences page</title>
- <graphic entityref="EtherealGUIColumnsPreferences" format="PNG"/>
- </figure>
- This page allows you to select which columns appear in the
- "Packet List" Pane.
- </para>
- <note><title>Note!</title>
- <para>
- Unlike all other preference changes, you will have to save the
- preferences and restart Ethereal in order for column changes to
- take effect!
- </para>
- </note>
- </section>
-
- <section><title>The "User Interface: Font" page</title>
- <para>
- <figure id="ChCustGUIFontPrefPage">
- <title>The "User Interface: Font" preferences page</title>
- <graphic entityref="EtherealGUIFontPreferences" format="PNG"/>
- </figure>
- This page allows you to select which font to use.
- </para>
- </section>
-
- <section><title>The "User Interface: Colors" page</title>
- <para>
- <figure id="ChCustGUIColrsPrefPage">
- <title>The "User Interface: Colors" preferences page</title>
- <graphic entityref="EtherealGUIColorsPreferences" format="PNG"/>
- </figure>
- This page allows you to select which colors to use.
- </para>
- </section>
-
- <section><title>The "Capture" page</title>
- <para>
- <figure id="ChCustCapturePrefPage">
- <title>The "Capture" preferences page</title>
- <graphic entityref="EtherealCapturePreferences" format="PNG"/>
- </figure>
- This page allows you to select some defaults for the capture options dialog.
- </para>
- </section>
-
- <section><title>The "Printing" page</title>
- <para>
- <figure id="ChCustPrintingPrefPage">
- <title>The "Printing" preferences page</title>
- <graphic entityref="EtherealPrintingPreferences" format="PNG"/>
- </figure>
- This page allows you to select some defaults for the print dialog.
- </para>
- </section>
-
- <section><title>The "Name Resolution" page</title>
- <para>
- <figure id="ChCustNameResolutionPrefPage">
- <title>The "Name Resolution" preferences page</title>
- <graphic entityref="EtherealNameResolutionPreferences" format="PNG"/>
- </figure>
- This page allows you to select some defaults for the name resolution.
- </para>
- </section>
-
- <section id="ChCustProtocolsPrefPages"><title>The "Protocols" pages</title>
- <para>
- These pages allows you to select settings for various protocols.
- </para>
- </section>
- </section>
-
-</chapter>
-<!-- End of EUG Chapter Customizing -->
-
+<!-- EUG Chapter Customizing --> +<!-- $Id$ --> + +<chapter id="ChapterCustomize"> + <title>Customizing Ethereal</title> + + <section id="ChCustIntroduction"><title>Introduction</title> + <para> + Ethereal's default behaviour will usually suit your needs pretty well. + However, as you become more familiar with Ethereal, it can be customized + in various ways to suit your needs even better. In this chapter we explore: + <itemizedlist> + <listitem> + <para> + How to start Ethereal with command line parameters + </para> + </listitem> + <listitem> + <para> + How to colorize the <application>Ethereal</application> display + </para> + </listitem> + <listitem> + <para> + How to use the various preference settings + </para> + </listitem> + </itemizedlist> + </para> + </section> + + <section id="ChCustCommandLine"><title>Start Ethereal from the command line</title> + <para> + You can start <application>Ethereal</application> from the command + line, but it can also be started from most Window managers + as well. In this section we will look at starting it from the command + line. + </para> + <para> + <application>Ethereal</application> supports a large number of + command line parameters. To see what they are, simply enter the + command <command> ethereal -h</command> and the help information + shown in <xref linkend="ChCustEx1"/> (or something similar) should be + printed. + <example id="ChCustEx1"> + <title>Help information available from Ethereal</title> + <programlisting> +This is GNU ethereal 0.10.5 +Compiled with GTK+ 2.4.3, with GLib 2.4.2, with WinPcap (version unknown), +with libz 1.2.1, with libpcre 4.4, with Net-SNMP 5.1, with ADNS. + +Running with WinPcap version 3.0 (packet.dll version 3, 1, 0, 20), based +on libpcap version 0.8 on Windows XP Service Pack 1, build 2600. + +ethereal [ -vh ] [ -klLnpQS ] [ -a <capture autostop condition> ] ... + [ -b <number of ringbuffer files>[:<duration>] ] + [ -B <byte view height> ] [ -c <count> ] [ -f <capture filter> ] + [ -i <interface> ] [ -m <medium font> ] [ -N <resolving> ] + [ -o <preference setting> ] ... [ -P <packet list height> ] + [ -r <infile> ] [ -R <read filter> ] [ -s <snaplen> ] + [ -t <time stamp format> ] [ -T <tree view height> ] + [ -w <savefile> ] [ -y <link type> ] [ -z <statistics string> ] + [ <infile> ] + </programlisting> + </example> + + We will examine each of the command line options in turn. + </para> + <para> + The first thing to notice is that issuing the command + <command>ethereal</command> by itself will bring up + <application>Ethereal</application>. + However, you can include as many of the command line parameters as + you like. Their meanings are as follows ( in alphabetical order ): + XXX - is the alphabetical order a good choice? Maybe better task based? + <variablelist> + <varlistentry><term><command>-a <capture autostop condition></command></term> + <listitem> + <para> + Specify a criterion that specifies when Ethereal is to stop writing + to a capture file. The criterion is of the form test:value, where test + is one of: + <variablelist> + <varlistentry><term><command>duration</command></term> + <listitem><para> + Stop writing to a capture file after value of seconds have elapsed. + </para></listitem> + </varlistentry> + <varlistentry><term><command>filesize</command></term> + <listitem><para> + Stop writing to a capture file after it reaches a size of value + kilobytes (where a kilobyte is 1000 bytes, not 1024 bytes). + </para></listitem> + </varlistentry> + </variablelist> + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-b <number of ringbuffer files></command></term> + <listitem> + <para> + If a maximum capture file size was specified, cause Ethereal to run + in "ring buffer" mode, with the specified number of files. In "ring + buffer" mode, Ethereal will write to several capture files. Their + name is based on the number of the file and on the creation date and + time. + </para> + <para> + When the first capture file fills up, Ethereal will switch to writing + to the next file, until it fills up the last file, at which point + it'll discard the data in the first file (unless 0 is specified, in + which case, the number of files is unlimited) and start writing to + that file and so on. + </para> + <para> + If the optional duration is specified, Ethereal will switch also to + the next file when the specified number of seconds has elapsed even + if the current file is not completely fills up. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-B <byte view height></command></term> + <listitem> + <para> + This option sets the initial height of the "Packet Bytes" pane. + This pane is usually the bottom pane in the Ethereal display. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-c <count></command></term> + <listitem> + <para> + This option specifies the maximum number of packets to capture + when capturing live data. It would be used in conjunction + with the <command>-k</command> option. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-f <capture filter></command></term> + <listitem> + <para> + This option sets the initial capture filter expression to + be used when capturing packets. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-h</command></term> + <listitem> + <para> + The <command>-h</command> option requests Ethereal to print + its version and usage instructions (as shown above) and exit. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-i <interface></command></term> + <listitem> + <para> + The <command>-i</command> option allows you to specify, + from the command line, which interface packet capture should + occur on if capturing packets. + </para> + <para> + An example would be: <command>ethereal -i eth0</command>. + </para> + <para> + To get a listing of all the interfaces you can capture on, + use the command <command>ifconfig -a</command> or + <command>netstat -i</command>. Unfortunately, some versions of + UNIX do not support <command>ifconfig -a</command>, so you + will have to use <command>netstat -i</command> in these cases. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-k</command></term> + <listitem> + <para> + The <command>-k</command> option specifies that Ethereal + should start capturing packets immediately. This option + requires the use of the <command>-i</command> parameter to + specify the interface that packet capture will occur from. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-l</command></term> + <listitem> + <para> + This option turns on automatic scrolling if the packet + list pane is being updated automatically as packets arrive + during a capture ( as specified by the <command>-S</command> + flag). + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-L</command></term> + <listitem> + <para> + List the data link types supported by the interface and exit. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-m <medium font></command></term> + <listitem> + <para> + This option sets the name of the font used for most text + displayed by Ethereal. XXX - add an example! + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-n</command></term> + <listitem> + <para> + Disable network object name resolution (such as hostname, TCP and UDP + port names). + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-N <resolving></command></term> + <listitem> + <para> + Turns on name resolving for particular types of addresses + and port numbers; the argument is a string that may contain + the letters <command>m</command> to enable MAC address + resolution, <command>n</command> to enable network address + resolution, and <command>t</command> to enable transport-layer + port number resolution. This overrides <command>-n</command> + if both <command>-N</command> and <command>-n</command> are + present. The letter C enables concurrent (asynchronous) DNS lookups. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command>-o <preference settings></command></term> + <listitem> + <para> + Sets a preference value, overriding the default value and + any value read from a preference file. The argument to the + flag is a string of the form prefname:value, where prefname + is the name of the preference (which is the same name that + would appear in the preference file), and value is the value + to which it should be set. Multiple instances of + <command>-o <preference settings> </command> can be + given on a single command line. + </para> + <para>An example of setting a single preference would be: </para> + <para> + <command> + ethereal -o mgcp.display_dissect_tree:TRUE + </command> + </para> + <para> + An example of setting multiple preferences would be: + </para> + <para> + <command> + ethereal -o mgcp.display_dissect_tree:TRUE -o mgcp.udp.callagent_port:2627 + </command> + </para> + <tip><title>Tip!</title> + <para> + You can get a list of all available preference strings from the + preferences file, see <xref linkend="AppFiles"/>. + </para> + </tip> + </listitem> + </varlistentry> + <varlistentry><term><command>-p</command></term> + <listitem> + <para> + Don't put the interface into promiscuous mode. Note that + the interface might be in promiscuous mode for some other + reason; hence, -p cannot be used to ensure that the only + traffic that is captured is traffic sent to or from the + machine on which Ethereal is running, broadcast traffic, and + multicast traffic to addresses received by that machine. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command>-P <packet list height></command></term> + <listitem> + <para> + This option sets the initial height of the "Packet List" pane, + ie, the top pane. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-Q</command></term> + <listitem> + <para> + This option forces Ethereal to exit when capturing is + complete. It can be used with the <command>-c</command> option. + It must be used in conjunction with the + <command>-i</command> and <command>-w</command> options. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-r <infile></command></term> + <listitem> + <para> + This option provides the name of a capture file for Ethereal + to read and display. This capture file can be in one of the + formats Ethereal understands. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-R <read filter></command></term> + <listitem> + <para> + This option specifies a display filter to be applied when + reading packets from a capture file. The syntax of this + filter is that of the display filters discussed in + <xref linkend="ChWorkDisplayFilterSection"/>. Packets not + matching the filter are discarded. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-s <snaplen></command></term> + <listitem> + <para> + This option specifies the snapshot length to use when + capturing packets. Ethereal will only capture + <command><snaplen></command> bytes of data for each packet. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-S</command></term> + <listitem> + <para> + This option specifies that Ethereal will display packets as + it captures them. This is done by capturing in one process + and displaying them in a separate process. This is the same + as "Update list of packets in real time" in the Capture Options + dialog box. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command>-t <time stamp format></command></term> + <listitem> + <para> + This option sets the format of packet timestamps that are + displayed in the packet list window. The format can be one of: + <itemizedlist> + <listitem> + <para> + <command>r</command> relative, which specifies timestamps are + displayed relative to the first packet captured. + </para> + </listitem> + <listitem> + <para> + <command>a</command> absolute, which specifies that actual times + be displayed for all packets. + </para> + </listitem> + <listitem> + <para> + <command>ad</command> absolute with date, which specifies that + actual dates and times be displayed for all packets. + </para> + </listitem> + <listitem> + <para> + <command>d</command> delta, which specifies that timestamps + are relative to the previous packet. + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command>-T <tree view height></command></term> + <listitem> + <para> + This option sets the initial height of the "Packet Details" pane. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-v</command></term> + <listitem> + <para> + The <command>-v</command> option requests + Ethereal to print out its version information and exit. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-w <savefile></command></term> + <listitem> + <para> + This option sets the name of the <command>savefile</command> + to be used when saving a capture file. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-y <link type></command></term> + <listitem> + <para> + If a capture is started from the command line with -k, set the data + link type to use while capturing packets. The values reported by -L + are the values that can be used. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>-z <statistics-string></command></term> + <listitem> + <para> + Get Ethereal to collect various types of statistics and display the + result in a window that updates in semi-real time. + XXX - add more details here! + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </section> + + <section id="ChCustColorizationSection"><title>Packet colorization</title> + <para> + A very useful mechanism available in Ethereal is packet colorization. + You can set Ethereal up so that it colorizes packets according to a + filter. This allows you to emphasize the packets you are interested in. + </para> + <para> + To colorize packets, select the Coloring Rules... menu item from + the View menu, and Ethereal will pop up the "Coloring Rules" + dialog box as shown in <xref linkend="ChCustColoringRulesDialog"/>. + </para> + <figure id="ChCustColoringRulesDialog"> + <title>The "Coloring Rules" dialog box</title> + <graphic entityref="EtherealColoringRulesDialog" format="PNG"/> + </figure> + <para> + Once the Coloring Rules dialog box is up, there are a number + of buttons you can use, depending on whether or not you have any + color filters installed already. + </para> + <note><title>Note!</title> + <para> + You will need to carefully select the order that rules are listed + (and thus applied) as they are applied in order from top to bottom. + So, more specific rules need to be listed before more general rules. + For example, if you have a color rule for UDP before the one for DNS, + the color rule for DNS will never be applied (as DNS uses UDP, so the + UDP rule will be matching first). + </para> + </note> + <para> + If this is the first time you have used Coloring Rules, click on the New + button which will bring up the Edit color filter dialog box as shown in + <xref linkend="ChCustEditColorDialog"/>. + </para> + <figure id="ChCustEditColorDialog"> + <title>The "Edit Color Filter" dialog box</title> + <graphic entityref="EtherealEditColorDialog" format="PNG"/> + </figure> + <para> + In the Edit Color dialog box, simply enter a name for the color filter, + and enter a filter string in the Filter text field. + <xref linkend="ChCustEditColorDialog"/> shows the values + <command>arp</command> and <command>arp</command> which means that + the name of the color filter is <command>arp</command> and the filter + will select protocols of type <command>arp</command>. Once you have + entered these values, you can choose a foreground and background + color for packets that match the filter expression. Click on + <command>Foreground color...</command> or + <command>Background color...</command> to achieve this and + Ethereal will pop up the Choose foreground/background color for + protocol dialog box as shown in + <xref linkend="ChCustChooseColorDialog"/>. + </para> + <figure id="ChCustChooseColorDialog"> + <title>The "Choose color" dialog box</title> + <graphic entityref="EtherealChooseColorDialog" format="PNG"/> + </figure> + <para> + Select the color you desire for the selected packets and click on OK. + </para> + <note> + <title>Note!</title> + <para> + You must select a color in the colorbar next to the colorwheel to + load values into the RGB values. Alternatively, you can set the + values to select the color you want. + </para> + </note> + <para> + <xref linkend="ChCustColorFilterMany"/> shows an example of several color + filters being used in Ethereal. You may not like the color choices, + however, feel free to choose your own. + </para> + <figure id="ChCustColorFilterMany"> + <title>Using color filters with Ethereal</title> + <graphic entityref="EtherealThreePane1" format="PNG"/> + </figure> + </section> + + <section id="ChAdvProtocolDissectionSection"> + <title>Control Protocol dissection</title> + <para> + There are some ways, to let the user control how protocols are + dissected. + </para> + <para> + Each protocol has its own dissector, so dissecting a packet will + typically involve several dissectors. As Ethereal tries to find the + right dissector for each packet (using static "routes" and heuristics + "guessing"), it might choose the wrong dissector in your specific + case. For example, Ethereal won't know if you use a common protocol + on an uncommon TCP port, e.g. using HTTP on TCP port 800 instead of + the standard port 80. + </para> + <para> + There are two ways to control the relations between protocol + dissectors: disable a protocol dissector completely or temporarily + divert the way Ethereal calls the dissectors. + </para> + <section id="ChAdvEnabledProtocols"><title>The "Enabled Protocols" dialog + box</title> + <para> + The Enabled Protocols dialog box lets you enable or + disable specific protocols, all protocols are enabled by default. + When a protocol is disabled, Ethereal stops processing a packet + whenever that protocol is encountered. + </para> + <note><title>Note!</title> + <para> + Disabling a protocol will prevent information about higher-layer + protocols from being displayed. For example, + suppose you disabled the IP protocol and selected + a packet containing Ethernet, IP, TCP, and HTTP + information. The Ethernet information would be + displayed, but the IP, TCP and HTTP information + would not - disabling IP would prevent it and + the other protocols from being displayed. + </para> + </note> + <figure id="ChAdvEnabledProtocolsFig"> + <title>The "Enabled Protocols" dialog box</title> + <graphic entityref="EtherealEnabledProtocols" format="PNG"/> + </figure> + <para> + To disable or enable a protocol, simply click on it using the + mouse or press the space bar when the protocol is highlighted. + </para> + <warning><title>Warning!</title> + <para> + You have to use the Save button to save your settings. The OK or Apply + buttons will not save your changes, so they will be lost when Ethereal + is closed. + </para> + </warning> + <para> + You can choose from the following actions: + <orderedlist> + <listitem> + <para> + <command>Enable All</command> Enable all protocols in the list. + </para> + </listitem> + <listitem> + <para> + <command>Disable All</command> Disable all protocols in the list. + </para> + </listitem> + <listitem> + <para> + <command>Invert</command> Toggle the state of all protocols in the + list. + </para> + </listitem> + <listitem> + <para> + <command>OK</command> Apply the changes and close the dialog box. + </para> + </listitem> + <listitem> + <para> + <command>Apply</command> Apply the changes and keep the dialog box + open. + </para> + </listitem> + <listitem> + <para> + <command>Save</command> Save the settings to the disabled_protos, see + <xref linkend="AppFiles"/> for details. + </para> + </listitem> + <listitem> + <para> + <command>Cancel</command> Cancel the changes and close the dialog box. + </para> + </listitem> + </orderedlist> + </para> + </section> + + <section id="ChAdvDecodeAs"><title>User Specified Decodes</title> + <para> + The "Decode As" functionality let you temporarily divert specific + protocol dissections. This might be useful for example, if you do some + uncommon things on your network. + </para> + <para> + <figure id="ChAdvDecodeAsFig"> + <title>The "Decode As" dialog box</title> + <graphic scale="100" entityref="EtherealDecodeAs" format="PNG"/> + </figure> + The content of this dialog box depends on the selected packet when it + was opened. + <warning><title>Warning!</title> + <para> + The user specified decodes can not be saved. If you quit Ethereal, + these settings will be lost. + </para> + </warning> + <orderedlist> + <listitem> + <para> + <command>Decode</command> Decode packets the selected way. + </para> + </listitem> + <listitem> + <para> + <command>Do not decode</command> Do not decode packets the selected + way. + </para> + </listitem> + <listitem> + <para> + <command>Link/Network/Transport</command> Specify the way to decode + packets. Which of these pages are available, depends on the content + of the selected packet when this dialog box was opened. + </para> + </listitem> + <listitem> + <para> + <command>Show Current</command> Open a dialog box showing the + current list of user specified decodes. + </para> + </listitem> + <listitem> + <para> + <command>OK</command> Apply the currently selected decode and close + the dialog box. + </para> + </listitem> + <listitem> + <para> + <command>Apply</command> Apply the currently selected decode and keep + the dialog box open. + </para> + </listitem> + <listitem> + <para> + <command>Cancel</command> Cancel the changes and close the dialog box. + </para> + </listitem> + </orderedlist> + </para> + </section> + + <section id="ChAdvDecodeAsShow"><title>Show User Specified Decodes</title> + <para> + This dialog box shows the currently active user specified decodes. + <figure id="ChAdvDecodeAsShowFig"> + <title>The "Decode As: Show" dialog box</title> + <graphic entityref="EtherealDecodeAsShow" format="PNG"/> + </figure> + <orderedlist> + <listitem> + <para> + <command>OK</command> Close this dialog box. + </para> + </listitem> + <listitem> + <para> + <command>Clear</command> Removes all user specified decodes. + </para> + </listitem> + </orderedlist> + </para> + </section> + </section> + + <section id="ChCustPreferencesSection"><title>Preferences</title> + <para> + There are a number of preferences you can set. Simply + select the Preferences... menu item from the Edit menu, and Ethereal + will pop up the Preferences dialog box as shown in + <xref linkend="ChCustGUIPrefPage"/>, with the "User Interface" page as + default. On the left side is a tree where you can select the page to be + shown. XXX - add detailed descriptions of all the preferences pages. + <warning> + <title>Warning!</title> + <para> + The OK or Apply button will not save the preference settings, + you'll have to save the settings by clicking the Save button. + </para> + </warning> + <itemizedlist> + <listitem> + <para> + The <command>OK</command> button will apply the preferences + settings and close the dialog. + </para> + </listitem> + <listitem> + <para> + The <command>Apply</command> button will apply the preferences + settings and keep the dialog open. + </para> + </listitem> + <listitem> + <para> + The <command>Save</command> button will apply the preferences + settings, save the settings on the harddisk and keep the dialog open. + </para> + </listitem> + <listitem> + <para> + The <command>Cancel</command> button will restore all preferences + settings to the last saved state. + </para> + </listitem> + </itemizedlist> + </para> + <section><title>The "User Interface" page</title> + <figure id="ChCustGUIPrefPage"> + <title>The "User Interface" preferences page</title> + <graphic entityref="EtherealGUIPreferences" format="PNG"/> + </figure> + <para> + This page allows you to configure various characteristics + of the GUI. + </para> + </section> + <section><title>The "User Interface: Layout" page</title> + <figure id="ChCustGUILayoutPrefPage"> + <title>The "User Interface: Layout" preferences page</title> + <graphic entityref="EtherealGUILayoutPreferences" format="PNG"/> + </figure> + <para> + This page selects the GUI layout of the main window. + </para> + </section> + <section><title>The "User Interface: Columns" page</title> + <para> + <figure id="ChCustGUIColumnsPrefPage"> + <title>The "User Interface: Columns" preferences page</title> + <graphic entityref="EtherealGUIColumnsPreferences" format="PNG"/> + </figure> + This page allows you to select which columns appear in the + "Packet List" Pane. + </para> + <note><title>Note!</title> + <para> + Unlike all other preference changes, you will have to save the + preferences and restart Ethereal in order for column changes to + take effect! + </para> + </note> + </section> + + <section><title>The "User Interface: Font" page</title> + <para> + <figure id="ChCustGUIFontPrefPage"> + <title>The "User Interface: Font" preferences page</title> + <graphic entityref="EtherealGUIFontPreferences" format="PNG"/> + </figure> + This page allows you to select which font to use. + </para> + </section> + + <section><title>The "User Interface: Colors" page</title> + <para> + <figure id="ChCustGUIColrsPrefPage"> + <title>The "User Interface: Colors" preferences page</title> + <graphic entityref="EtherealGUIColorsPreferences" format="PNG"/> + </figure> + This page allows you to select which colors to use. + </para> + </section> + + <section><title>The "Capture" page</title> + <para> + <figure id="ChCustCapturePrefPage"> + <title>The "Capture" preferences page</title> + <graphic entityref="EtherealCapturePreferences" format="PNG"/> + </figure> + This page allows you to select some defaults for the capture options dialog. + </para> + </section> + + <section><title>The "Printing" page</title> + <para> + <figure id="ChCustPrintingPrefPage"> + <title>The "Printing" preferences page</title> + <graphic entityref="EtherealPrintingPreferences" format="PNG"/> + </figure> + This page allows you to select some defaults for the print dialog. + </para> + </section> + + <section><title>The "Name Resolution" page</title> + <para> + <figure id="ChCustNameResolutionPrefPage"> + <title>The "Name Resolution" preferences page</title> + <graphic entityref="EtherealNameResolutionPreferences" format="PNG"/> + </figure> + This page allows you to select some defaults for the name resolution. + </para> + </section> + + <section id="ChCustProtocolsPrefPages"><title>The "Protocols" pages</title> + <para> + These pages allows you to select settings for various protocols. + </para> + </section> + </section> + +</chapter> +<!-- End of EUG Chapter Customizing --> + diff --git a/docbook/ug-src/EUG_chapter_introduction.xml b/docbook/ug-src/EUG_chapter_introduction.xml index 1727011404..f328c1e77f 100644 --- a/docbook/ug-src/EUG_chapter_introduction.xml +++ b/docbook/ug-src/EUG_chapter_introduction.xml @@ -1,556 +1,558 @@ -<!-- EUG Chapter Introduction -->
-<chapter id="ChapterIntroduction">
- <title>Introduction</title>
- <!-- Introduction -->
- <section id="ChIntroWhatIs">
- <title>What is <application>Ethereal?</application></title>
- <para>
- Ethereal is a network packet analyzer. A network packet
- analyzer will try to capture network packets and tries to display
- that packet data as detailed as possible.
- </para>
- <para>
- You could think of a network packet analyzer as a measuring device used to
- examine what's going on inside a network cable, just like a voltmeter is
- used by an electrician to examine what's going on inside an electric cable
- (but at a higher level, of course).
- </para>
- <para>
- In the past, such tools were either very expensive, proprietary, or both.
- However, with the advent of Ethereal, all that has changed.
- </para>
- <para>
- <application>Ethereal</application> is perhaps one of the best open
- source packet analyzers available today.
- </para>
-
- <section id="ChIntroPurposes"><title>Some intended purposes</title>
- <para>
- Here are some examples people use Ethereal for:
- <itemizedlist>
- <listitem><para>
- network administrators use it to <command>troubleshoot network
- problems</command>
- </para></listitem>
- <listitem><para>
- network security engineers use it to <command>examine security
- problems</command>
- </para></listitem>
- <listitem><para>
- developers use it to <command>debug protocol implementations</command>
- </para></listitem>
- <listitem><para>
- people use it to <command>learn network protocol</command>
- internals
- </para></listitem>
- </itemizedlist>
- Beside these examples, Ethereal can be helpful in many other situations
- too.
- </para>
- </section>
-
- <section id="ChIntroFeatures"><title>Features</title>
- <para>
- The following are some of the many features Ethereal provides:
- <itemizedlist>
- <listitem>
- <para>Available for <command>UNIX</command> and <command>Windows</command>.</para>
- </listitem>
- <listitem>
- <para>
- <command>Capture</command> live packet data from a network interface.
- </para>
- </listitem>
- <listitem>
- <para>
- Display packets with <command>very detailed protocol information</command>.
- </para>
- </listitem>
- <listitem>
- <para>
- <command>Open and Save</command> packet data captured.
- </para>
- </listitem>
- <listitem>
- <para>
- <command>Import and Export</command> packet data from and to a lot of
- other capture programs.
- </para>
- </listitem>
- <listitem>
- <para><command>Filter packets</command> on many criteria.</para>
- </listitem>
- <listitem>
- <para><command>Search</command> for packets on many criteria.</para>
- </listitem>
- <listitem>
- <para><command>Colorize</command> packet display based on filters.</para>
- </listitem>
- <listitem>
- <para>Create various <command>statistics</command>.</para>
- </listitem>
- <listitem>
- <para>... and <command>a lot more!</command></para>
- </listitem>
- </itemizedlist>
- However, to really appreciate its power, you have to start using it.
- </para>
- <para>
- <xref linkend="ChIntroFig1"/> shows <application>Ethereal</application>
- having captured some packets and waiting for you to examine
- them.
- <figure id="ChIntroFig1">
- <title>
- <application>Ethereal</application> captures packets and allows
- you to examine their content.
- </title>
- <graphic entityref="EtherealMain1" format="PNG"/>
- </figure>
- </para>
- </section>
-
- <section>
- <title>Live capture from many different network media</title>
- <para>
- Despite its name, Ethereal can capture traffic from
- network media other than Ethernet. Which media types are
- supported, depends on many things like the operating system you are
- using. An overview of the supported media types can be found at:
- <ulink url="&EtherealMediaPage;"/>.
- </para>
- </section>
-
- <section><title>Import files from many other capture programs</title>
- <para>
- Ethereal can open packets captured from a large number of
- other capture programs. For a list of input formats see
- <xref linkend="ChIOInputFormatsSection"/>.
- </para>
- </section>
- <section><title>Export files for many other capture programs</title>
- <para>
- Ethereal can save packets captured in a large number of formats of
- other capture programs. For a list of output formats see
- <xref linkend="ChIOOutputFormatsSection"/>.
- </para>
- </section>
-
- <section>
- <title>Many protocol decoders</title>
- <para>
- There are protocol decoders (or dissectors, as they are
- known in Ethereal) for a great many protocols:
- see <xref linkend="AppProtocols"/>.
- </para>
- </section>
-
- <section><title>Open Source Software</title>
- <para>
- Ethereal is an open source software project, and is released under
- the <ulink url="&GPLWebsite;">GNU General Public Licence</ulink> (GPL).
- You can freely use Ethereal on any number of computers you like, without
- worrying about license keys or fees or such. In addition, all source
- code is freely available under the GPL. Because of that, it is very easy
- for people to add new protocols to Ethereal, either as plugins, or built
- into the source, and they often do!
- </para>
- </section>
-
- <section id="ChIntroNoFeatures"><title>What Ethereal is not</title>
- <para>
- Here are some things Ethereal does not provide:
- <itemizedlist>
- <listitem><para>
- Ethereal isn't an intrusion detection system. It will not warn you when
- someone does strange things on your network that he/she isn't allowed to
- do. However, if strange things happen, Ethereal might help you figure
- out what is really going on.
- </para></listitem>
- <listitem><para>
- Ethereal will not manipulate things on the network, it will only
- "measure" things from it. Ethereal doesn't send packets on the network
- or do other active things (except for name resolutions, but even
- that can be disabled).
- </para></listitem>
- </itemizedlist>
- </para>
- </section>
- </section>
-
- <section id="ChIntroPlatforms">
- <title>Platforms Ethereal runs on</title>
- <para>
- Ethereal currently runs on most UNIX platforms and various Windows
- platforms. It requires GTK+, GLib, libpcap and some other libraries in
- order to run.
- </para>
- <para>
- If a binary package is not available for your platform, you should
- download the source and try to build it. Please report your experiences
- to <ulink url="mailto:&EtherealDevMailList;">&EtherealDevMailList;</ulink>.
- </para>
- <para>
- Binary packages are available for at least the following platforms:
- </para>
-
- <section><title>Unix</title>
- <para>
- <itemizedlist>
- <listitem><para>Apple Mac OS X</para></listitem>
- <listitem><para>BeOS</para></listitem>
- <listitem><para>FreeBSD</para></listitem>
- <listitem><para>HP-UX</para></listitem>
- <listitem><para>IBM AIX</para></listitem>
- <listitem><para>NetBSD</para></listitem>
- <listitem><para>OpenBSD</para></listitem>
- <listitem><para>SCO UnixWare/OpenUnix</para></listitem>
- <listitem><para>SGI Irix</para></listitem>
- <listitem><para>Sun Solaris/Intel</para></listitem>
- <listitem><para>Sun Solaris/Sparc</para></listitem>
- <listitem><para>Tru64 UNIX (formerly Digital UNIX)</para></listitem>
- </itemizedlist>
- </para>
- </section>
-
- <section><title>Linux</title>
- <para>
- <itemizedlist>
- <listitem><para>Debian GNU/Linux</para></listitem>
- <listitem><para>Gentoo Linux</para></listitem>
- <listitem><para>IBM S/390 Linux (Red Hat)</para></listitem>
- <listitem><para>Mandrake Linux</para></listitem>
- <listitem><para>PLD Linux</para></listitem>
- <listitem><para>Red Hat Linux</para></listitem>
- <listitem><para>Rock Linux</para></listitem>
- <listitem><para>Slackware Linux</para></listitem>
- <listitem><para>Suse Linux</para></listitem>
- </itemizedlist>
- </para>
- </section>
-
- <section><title>Microsoft Windows</title>
- <para>
- <itemizedlist>
- <listitem><para>Windows Me / 98 / 95</para></listitem>
- <listitem><para>Windows Server 2003 / XP / 2000 / NT 4.0</para></listitem>
- </itemizedlist>
- </para>
- </section>
-
- </section>
-
- <section id="ChIntroDownload">
- <title>Where to get Ethereal?</title>
- <para>
- You can get the latest copy of the program from the Ethereal website:
- <ulink url="&EtherealDownloadPage;">&EtherealDownloadPage;</ulink>. The
- website allows you to choose from among several mirrors for
- downloading.
- </para>
- <para>
- A new Ethereal version will typically become available every 4-8 weeks.
- </para>
- </section>
-
- <section id="ChIntroPronounce">
- <title>A rose by any other name</title>
- <para>
- William Shakespeare wrote:
- <emphasis>
- "A rose by any other name would smell as sweet."
- </emphasis>
- And so it is with Ethereal, as there appears to be two different
- ways that people pronounce the name.
- </para>
- <para>
- Some people pronounce it ether-real, while others pronounce it
- e-the-real, as in ghostly, insubstantial, etc.
- </para>
- <para>
- You are welcome to call it what you like, as long as you find it
- useful. The FAQ gives the official pronounciation as "e-the-real".
- </para>
- </section>
-
- <section id="ChIntroHistory">
- <title>A brief history of Ethereal</title>
- <para>
- In late 1997, Gerald Combs needed a tool for tracking down
- networking problems and wanted to learn more about networking, so
- he started writing Ethereal as a way to solve both problems.
- </para>
- <para>
- Ethereal was initially released, after several pauses in development,
- in July 1998 as version 0.2.0. Within days, patches, bug reports,
- and words of encouragement started arriving, so Ethereal was on its
- way to success.
- </para>
- <para>
- Not long after that Gilbert Ramirez saw its potential and contributed
- a low-level dissector to it.
- </para>
- <para>
- In October, 1998, Guy Harris of Network Appliance was looking for
- something better than tcpview, so he started applying patches and
- contributing dissectors to Ethereal.
- </para>
- <para>
- In late 1998, Richard Sharpe, who was giving TCP/IP courses, saw its
- potential on such courses, and started looking at it to see if it
- supported the protocols he needed. While it didn't at that point,
- new protocols could be easily added. So he started contributing
- dissectors and contributing patches.
- </para>
- <para>
- The list of people who have contributed to Ethereal has become very long
- since then, and almost all of them started with a protocol that they
- needed that Ethereal did not already handle. So they copied an existing
- dissector and contributed the code back to the team.
- </para>
- </section>
-
- <section id="ChIntroMaintenance">
- <title>
- Development and maintenance of <application>Ethereal</application>
- </title>
- <para>
- Ethereal was initially developed by Gerald Combs. Ongoing development
- and maintenance of Ethereal is handled by the Ethereal team, a loose
- group of individuals who fix bugs and provide new functionality.
- </para>
- <para>
- There have also been a large number of people who have contributed
- protocol dissectors to Ethereal, and it is expected that this will
- continue. You can find a list of the people who have contributed
- code to Ethereal by checking the about dialog box of Ethereal, or at
- the <ulink url="&EtherealAuthorsPage;">authors</ulink> page on the
- Ethereal web site.
- </para>
- <para>
- Ethereal is an open source software project, and is released under
- the <ulink url="&GPLWebsite;">GNU General Public Licence</ulink> (GPL).
- All source code is freely available under the GPL. You are welcome to
- modify Ethereal to suit your own needs, and it would be appreciated
- if you contribute your improvements back to the Ethereal team.
- </para>
- <para>
- You gain three benefits by contributing your improvements back to the
- community:
- <itemizedlist>
- <listitem>
- <para>
- Other people who find your contributions useful will appreciate
- them, and you will know that you have helped people in the
- same way that the developers of Ethereal have helped people.
- </para>
- </listitem>
- <listitem>
- <para>
- The developers of Ethereal might improve your changes even more,
- as there's always room for improvements. Or they may implement some
- advanced things on top of your code, which can be useful for yourself
- too.
- </para>
- </listitem>
- <listitem>
- <para>
- The maintainers and developers of Ethereal will maintain your
- code as well, fixing it when API changes or other changes are
- made, and generally keeping it in tune with what is happening
- with Ethereal. So if Ethereal is updated (which is done often),
- you can get a new Ethereal version from the website and your changes
- will already be included without any effort for you.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- The Ethereal source code and binary kits for some platforms are all
- available on the download page of the Ethereal website:
- <ulink url="&EtherealDownloadPage;">&EtherealDownloadPage;</ulink>.
- </para>
- </section>
-
- <section id="ChIntroHelp">
- <title>Reporting problems and getting help</title>
- <para>
- If you have problems, or need help with Ethereal, there are several
- places that may be of interest to you (well, beside this guide of
- course).
- </para>
-
- <section id="ChIntroFAQ"><title>FAQ</title>
- <para>
- The "Frequently Asked Questions" will list often asked questions and
- the corresponding answers.
- <note><title>Read the FAQ!</title>
- <para>
- Before sending any mail to the mailing lists below, be sure to read the
- FAQ, as it will often answer the question(s) you might have. This will save
- yourself and others a lot of time (keep in mind that a lot of people are
- subscribed to the mailing lists).
- </para>
- </note>
- You will find the FAQ inside Ethereal by clicking the menu item
- Help/Contents and selecting the FAQ page in the upcoming dialog.
- </para>
- <para>
- An online version is available at the ethereal website:
- <ulink url="&EtherealFAQPage;">&EtherealFAQPage;</ulink>. You might
- prefer this online version, as it's typically more up to date and the HTML
- format is easier to use.
- </para>
- </section>
-
- <section id="ChIntroMailingLists"><title>Mailing Lists</title>
- <para>
- There are several mailing lists of specific Ethereal topics available:
- <variablelist>
- <varlistentry><term><command>ethereal-announce</command></term>
- <listitem>
- <para>
- This mailing list will inform you about new program
- releases, which usually appear about every 4-8 weeks.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>ethereal-users</command></term>
- <listitem>
- <para>
- This list is for users of Ethereal. People post
- questions about building and using Ethereal, others (hopefully)
- provide answers.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>ethereal-dev</command></term>
- <listitem>
- <para>
- This list is for Ethereal developers. If you want to start
- developing a protocol dissector, join this list.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- You can subscribe to each of these lists from the Ethereal web site:
- <ulink url="&EtherealWebSite;">&EtherealWebSite;</ulink>. Simply
- select the <command>mailing lists</command> link on the left hand
- side of the site. The lists are archived at the Ethereal web site
- as well.
- <tip><title>Tip!</title>
- <para>
- You can search in the list archives to see if someone asked the same
- question some time before and maybe already got an answer. That way you
- don't have to wait until someone answers your question.
- </para>
- </tip>
- </para>
- </section>
-
- <section><title>Reporting Problems</title>
- <note><title>Note!</title>
- <para>
- Before reporting any problems, please make sure you have installed the
- latest version of Ethereal.
- </para>
- </note>
- <para>
- When reporting problems with Ethereal, it is helpful if you supply the
- following information:
- <orderedlist>
- <listitem>
- <para>
- The version number of Ethereal and the dependent libraries linked with
- it, eg GTK+, etc. You can obtain this with the command
- <command>ethereal -v</command>.
- </para>
- </listitem>
- <listitem>
- <para>
- Information about the platform you run Ethereal on.
- </para>
- </listitem>
- <listitem>
- <para>
- A detailed description of your problem.
- </para>
- </listitem>
- </orderedlist>
- </para>
- <note><title>Don't send large files!</title>
- <para>
- Do not send large files (>100KB) to the mailing lists, just place a note
- that further data is available on request. Large files will only annoy a
- lot of people on the list who are not interested in your specific problem.
- If required, you will be asked for further data by the persons who really
- can help you.
- </para>
- </note>
- <note><title>Don't send confidential information!</title>
- <para>
- If you send captured data to the mailing lists, be sure they don't contain
- any sensitive or confidential information like passwords or such.
- </para>
- </note>
- </section>
-
- <section><title>Reporting Crashes on UNIX/Linux platforms</title>
- <para>
- When reporting crashes with Ethereal, it is helpful if you supply the
- traceback information (besides the information mentioned in "Reporting
- Problems").
- </para>
- <para>
- You can obtain this traceback information with the following commands:
- <programlisting>
-<![CDATA[
-$ gdb `whereis ethereal | cut -f2 -d: | cut -d' ' -f2` core >& bt.txt
-backtrace
-^D
-$
-]]>
- </programlisting>
- <note>
- <para>
- Type the characters in the first line verbatim! Those are
- back-tics there!
- </para>
- </note>
- <note>
- <para>
- backtrace is a <command>gdb</command> command. You should
- enter it verbatim after the first line shown above, but it will not be
- echoed. The ^D
- (Control-D, that is, press the Control key and the D key
- together) will cause <command>gdb</command> to exit. This will
- leave you with a file called
- <filename>bt.txt</filename> in the current directory.
- Include the file with your bug report.
- </para>
- </note>
- <note>
- <para>
- If you do not have <command>gdb</command> available, you
- will have to check out your operating system's debugger.
- </para>
- </note>
- </para>
- <para>
- You should mail the traceback to the
- <ulink url="mailto:&EtherealDevMailList;">&EtherealDevMailList;</ulink>
- mailing list.
- </para>
- </section>
-
- <section><title>Reporting Crashes on Windows platforms</title>
- <para>
- The Windows distributions don't contain the symbol files (.pdb), because
- they are very large. For this reason it's not possible to create
- a meaningful backtrace file from it. You should report your crash just
- like other problems, using the mechanism described above.
- </para>
- </section>
- </section>
-
-</chapter>
-<!-- End of EUG Chapter 1 -->
+<!-- EUG Chapter Introduction --> +<!-- $Id$ --> + +<chapter id="ChapterIntroduction"> + <title>Introduction</title> + <!-- Introduction --> + <section id="ChIntroWhatIs"> + <title>What is <application>Ethereal?</application></title> + <para> + Ethereal is a network packet analyzer. A network packet + analyzer will try to capture network packets and tries to display + that packet data as detailed as possible. + </para> + <para> + You could think of a network packet analyzer as a measuring device used to + examine what's going on inside a network cable, just like a voltmeter is + used by an electrician to examine what's going on inside an electric cable + (but at a higher level, of course). + </para> + <para> + In the past, such tools were either very expensive, proprietary, or both. + However, with the advent of Ethereal, all that has changed. + </para> + <para> + <application>Ethereal</application> is perhaps one of the best open + source packet analyzers available today. + </para> + + <section id="ChIntroPurposes"><title>Some intended purposes</title> + <para> + Here are some examples people use Ethereal for: + <itemizedlist> + <listitem><para> + network administrators use it to <command>troubleshoot network + problems</command> + </para></listitem> + <listitem><para> + network security engineers use it to <command>examine security + problems</command> + </para></listitem> + <listitem><para> + developers use it to <command>debug protocol implementations</command> + </para></listitem> + <listitem><para> + people use it to <command>learn network protocol</command> + internals + </para></listitem> + </itemizedlist> + Beside these examples, Ethereal can be helpful in many other situations + too. + </para> + </section> + + <section id="ChIntroFeatures"><title>Features</title> + <para> + The following are some of the many features Ethereal provides: + <itemizedlist> + <listitem> + <para>Available for <command>UNIX</command> and <command>Windows</command>.</para> + </listitem> + <listitem> + <para> + <command>Capture</command> live packet data from a network interface. + </para> + </listitem> + <listitem> + <para> + Display packets with <command>very detailed protocol information</command>. + </para> + </listitem> + <listitem> + <para> + <command>Open and Save</command> packet data captured. + </para> + </listitem> + <listitem> + <para> + <command>Import and Export</command> packet data from and to a lot of + other capture programs. + </para> + </listitem> + <listitem> + <para><command>Filter packets</command> on many criteria.</para> + </listitem> + <listitem> + <para><command>Search</command> for packets on many criteria.</para> + </listitem> + <listitem> + <para><command>Colorize</command> packet display based on filters.</para> + </listitem> + <listitem> + <para>Create various <command>statistics</command>.</para> + </listitem> + <listitem> + <para>... and <command>a lot more!</command></para> + </listitem> + </itemizedlist> + However, to really appreciate its power, you have to start using it. + </para> + <para> + <xref linkend="ChIntroFig1"/> shows <application>Ethereal</application> + having captured some packets and waiting for you to examine + them. + <figure id="ChIntroFig1"> + <title> + <application>Ethereal</application> captures packets and allows + you to examine their content. + </title> + <graphic entityref="EtherealMain1" format="PNG"/> + </figure> + </para> + </section> + + <section> + <title>Live capture from many different network media</title> + <para> + Despite its name, Ethereal can capture traffic from + network media other than Ethernet. Which media types are + supported, depends on many things like the operating system you are + using. An overview of the supported media types can be found at: + <ulink url="&EtherealMediaPage;"/>. + </para> + </section> + + <section><title>Import files from many other capture programs</title> + <para> + Ethereal can open packets captured from a large number of + other capture programs. For a list of input formats see + <xref linkend="ChIOInputFormatsSection"/>. + </para> + </section> + <section><title>Export files for many other capture programs</title> + <para> + Ethereal can save packets captured in a large number of formats of + other capture programs. For a list of output formats see + <xref linkend="ChIOOutputFormatsSection"/>. + </para> + </section> + + <section> + <title>Many protocol decoders</title> + <para> + There are protocol decoders (or dissectors, as they are + known in Ethereal) for a great many protocols: + see <xref linkend="AppProtocols"/>. + </para> + </section> + + <section><title>Open Source Software</title> + <para> + Ethereal is an open source software project, and is released under + the <ulink url="&GPLWebsite;">GNU General Public Licence</ulink> (GPL). + You can freely use Ethereal on any number of computers you like, without + worrying about license keys or fees or such. In addition, all source + code is freely available under the GPL. Because of that, it is very easy + for people to add new protocols to Ethereal, either as plugins, or built + into the source, and they often do! + </para> + </section> + + <section id="ChIntroNoFeatures"><title>What Ethereal is not</title> + <para> + Here are some things Ethereal does not provide: + <itemizedlist> + <listitem><para> + Ethereal isn't an intrusion detection system. It will not warn you when + someone does strange things on your network that he/she isn't allowed to + do. However, if strange things happen, Ethereal might help you figure + out what is really going on. + </para></listitem> + <listitem><para> + Ethereal will not manipulate things on the network, it will only + "measure" things from it. Ethereal doesn't send packets on the network + or do other active things (except for name resolutions, but even + that can be disabled). + </para></listitem> + </itemizedlist> + </para> + </section> + </section> + + <section id="ChIntroPlatforms"> + <title>Platforms Ethereal runs on</title> + <para> + Ethereal currently runs on most UNIX platforms and various Windows + platforms. It requires GTK+, GLib, libpcap and some other libraries in + order to run. + </para> + <para> + If a binary package is not available for your platform, you should + download the source and try to build it. Please report your experiences + to <ulink url="mailto:&EtherealDevMailList;">&EtherealDevMailList;</ulink>. + </para> + <para> + Binary packages are available for at least the following platforms: + </para> + + <section><title>Unix</title> + <para> + <itemizedlist> + <listitem><para>Apple Mac OS X</para></listitem> + <listitem><para>BeOS</para></listitem> + <listitem><para>FreeBSD</para></listitem> + <listitem><para>HP-UX</para></listitem> + <listitem><para>IBM AIX</para></listitem> + <listitem><para>NetBSD</para></listitem> + <listitem><para>OpenBSD</para></listitem> + <listitem><para>SCO UnixWare/OpenUnix</para></listitem> + <listitem><para>SGI Irix</para></listitem> + <listitem><para>Sun Solaris/Intel</para></listitem> + <listitem><para>Sun Solaris/Sparc</para></listitem> + <listitem><para>Tru64 UNIX (formerly Digital UNIX)</para></listitem> + </itemizedlist> + </para> + </section> + + <section><title>Linux</title> + <para> + <itemizedlist> + <listitem><para>Debian GNU/Linux</para></listitem> + <listitem><para>Gentoo Linux</para></listitem> + <listitem><para>IBM S/390 Linux (Red Hat)</para></listitem> + <listitem><para>Mandrake Linux</para></listitem> + <listitem><para>PLD Linux</para></listitem> + <listitem><para>Red Hat Linux</para></listitem> + <listitem><para>Rock Linux</para></listitem> + <listitem><para>Slackware Linux</para></listitem> + <listitem><para>Suse Linux</para></listitem> + </itemizedlist> + </para> + </section> + + <section><title>Microsoft Windows</title> + <para> + <itemizedlist> + <listitem><para>Windows Me / 98 / 95</para></listitem> + <listitem><para>Windows Server 2003 / XP / 2000 / NT 4.0</para></listitem> + </itemizedlist> + </para> + </section> + + </section> + + <section id="ChIntroDownload"> + <title>Where to get Ethereal?</title> + <para> + You can get the latest copy of the program from the Ethereal website: + <ulink url="&EtherealDownloadPage;">&EtherealDownloadPage;</ulink>. The + website allows you to choose from among several mirrors for + downloading. + </para> + <para> + A new Ethereal version will typically become available every 4-8 weeks. + </para> + </section> + + <section id="ChIntroPronounce"> + <title>A rose by any other name</title> + <para> + William Shakespeare wrote: + <emphasis> + "A rose by any other name would smell as sweet." + </emphasis> + And so it is with Ethereal, as there appears to be two different + ways that people pronounce the name. + </para> + <para> + Some people pronounce it ether-real, while others pronounce it + e-the-real, as in ghostly, insubstantial, etc. + </para> + <para> + You are welcome to call it what you like, as long as you find it + useful. The FAQ gives the official pronounciation as "e-the-real". + </para> + </section> + + <section id="ChIntroHistory"> + <title>A brief history of Ethereal</title> + <para> + In late 1997, Gerald Combs needed a tool for tracking down + networking problems and wanted to learn more about networking, so + he started writing Ethereal as a way to solve both problems. + </para> + <para> + Ethereal was initially released, after several pauses in development, + in July 1998 as version 0.2.0. Within days, patches, bug reports, + and words of encouragement started arriving, so Ethereal was on its + way to success. + </para> + <para> + Not long after that Gilbert Ramirez saw its potential and contributed + a low-level dissector to it. + </para> + <para> + In October, 1998, Guy Harris of Network Appliance was looking for + something better than tcpview, so he started applying patches and + contributing dissectors to Ethereal. + </para> + <para> + In late 1998, Richard Sharpe, who was giving TCP/IP courses, saw its + potential on such courses, and started looking at it to see if it + supported the protocols he needed. While it didn't at that point, + new protocols could be easily added. So he started contributing + dissectors and contributing patches. + </para> + <para> + The list of people who have contributed to Ethereal has become very long + since then, and almost all of them started with a protocol that they + needed that Ethereal did not already handle. So they copied an existing + dissector and contributed the code back to the team. + </para> + </section> + + <section id="ChIntroMaintenance"> + <title> + Development and maintenance of <application>Ethereal</application> + </title> + <para> + Ethereal was initially developed by Gerald Combs. Ongoing development + and maintenance of Ethereal is handled by the Ethereal team, a loose + group of individuals who fix bugs and provide new functionality. + </para> + <para> + There have also been a large number of people who have contributed + protocol dissectors to Ethereal, and it is expected that this will + continue. You can find a list of the people who have contributed + code to Ethereal by checking the about dialog box of Ethereal, or at + the <ulink url="&EtherealAuthorsPage;">authors</ulink> page on the + Ethereal web site. + </para> + <para> + Ethereal is an open source software project, and is released under + the <ulink url="&GPLWebsite;">GNU General Public Licence</ulink> (GPL). + All source code is freely available under the GPL. You are welcome to + modify Ethereal to suit your own needs, and it would be appreciated + if you contribute your improvements back to the Ethereal team. + </para> + <para> + You gain three benefits by contributing your improvements back to the + community: + <itemizedlist> + <listitem> + <para> + Other people who find your contributions useful will appreciate + them, and you will know that you have helped people in the + same way that the developers of Ethereal have helped people. + </para> + </listitem> + <listitem> + <para> + The developers of Ethereal might improve your changes even more, + as there's always room for improvements. Or they may implement some + advanced things on top of your code, which can be useful for yourself + too. + </para> + </listitem> + <listitem> + <para> + The maintainers and developers of Ethereal will maintain your + code as well, fixing it when API changes or other changes are + made, and generally keeping it in tune with what is happening + with Ethereal. So if Ethereal is updated (which is done often), + you can get a new Ethereal version from the website and your changes + will already be included without any effort for you. + </para> + </listitem> + </itemizedlist> + </para> + <para> + The Ethereal source code and binary kits for some platforms are all + available on the download page of the Ethereal website: + <ulink url="&EtherealDownloadPage;">&EtherealDownloadPage;</ulink>. + </para> + </section> + + <section id="ChIntroHelp"> + <title>Reporting problems and getting help</title> + <para> + If you have problems, or need help with Ethereal, there are several + places that may be of interest to you (well, beside this guide of + course). + </para> + + <section id="ChIntroFAQ"><title>FAQ</title> + <para> + The "Frequently Asked Questions" will list often asked questions and + the corresponding answers. + <note><title>Read the FAQ!</title> + <para> + Before sending any mail to the mailing lists below, be sure to read the + FAQ, as it will often answer the question(s) you might have. This will save + yourself and others a lot of time (keep in mind that a lot of people are + subscribed to the mailing lists). + </para> + </note> + You will find the FAQ inside Ethereal by clicking the menu item + Help/Contents and selecting the FAQ page in the upcoming dialog. + </para> + <para> + An online version is available at the ethereal website: + <ulink url="&EtherealFAQPage;">&EtherealFAQPage;</ulink>. You might + prefer this online version, as it's typically more up to date and the HTML + format is easier to use. + </para> + </section> + + <section id="ChIntroMailingLists"><title>Mailing Lists</title> + <para> + There are several mailing lists of specific Ethereal topics available: + <variablelist> + <varlistentry><term><command>ethereal-announce</command></term> + <listitem> + <para> + This mailing list will inform you about new program + releases, which usually appear about every 4-8 weeks. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>ethereal-users</command></term> + <listitem> + <para> + This list is for users of Ethereal. People post + questions about building and using Ethereal, others (hopefully) + provide answers. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>ethereal-dev</command></term> + <listitem> + <para> + This list is for Ethereal developers. If you want to start + developing a protocol dissector, join this list. + </para> + </listitem> + </varlistentry> + </variablelist> + You can subscribe to each of these lists from the Ethereal web site: + <ulink url="&EtherealWebSite;">&EtherealWebSite;</ulink>. Simply + select the <command>mailing lists</command> link on the left hand + side of the site. The lists are archived at the Ethereal web site + as well. + <tip><title>Tip!</title> + <para> + You can search in the list archives to see if someone asked the same + question some time before and maybe already got an answer. That way you + don't have to wait until someone answers your question. + </para> + </tip> + </para> + </section> + + <section><title>Reporting Problems</title> + <note><title>Note!</title> + <para> + Before reporting any problems, please make sure you have installed the + latest version of Ethereal. + </para> + </note> + <para> + When reporting problems with Ethereal, it is helpful if you supply the + following information: + <orderedlist> + <listitem> + <para> + The version number of Ethereal and the dependent libraries linked with + it, eg GTK+, etc. You can obtain this with the command + <command>ethereal -v</command>. + </para> + </listitem> + <listitem> + <para> + Information about the platform you run Ethereal on. + </para> + </listitem> + <listitem> + <para> + A detailed description of your problem. + </para> + </listitem> + </orderedlist> + </para> + <note><title>Don't send large files!</title> + <para> + Do not send large files (>100KB) to the mailing lists, just place a note + that further data is available on request. Large files will only annoy a + lot of people on the list who are not interested in your specific problem. + If required, you will be asked for further data by the persons who really + can help you. + </para> + </note> + <note><title>Don't send confidential information!</title> + <para> + If you send captured data to the mailing lists, be sure they don't contain + any sensitive or confidential information like passwords or such. + </para> + </note> + </section> + + <section><title>Reporting Crashes on UNIX/Linux platforms</title> + <para> + When reporting crashes with Ethereal, it is helpful if you supply the + traceback information (besides the information mentioned in "Reporting + Problems"). + </para> + <para> + You can obtain this traceback information with the following commands: + <programlisting> +<![CDATA[ +$ gdb `whereis ethereal | cut -f2 -d: | cut -d' ' -f2` core >& bt.txt +backtrace +^D +$ +]]> + </programlisting> + <note> + <para> + Type the characters in the first line verbatim! Those are + back-tics there! + </para> + </note> + <note> + <para> + backtrace is a <command>gdb</command> command. You should + enter it verbatim after the first line shown above, but it will not be + echoed. The ^D + (Control-D, that is, press the Control key and the D key + together) will cause <command>gdb</command> to exit. This will + leave you with a file called + <filename>bt.txt</filename> in the current directory. + Include the file with your bug report. + </para> + </note> + <note> + <para> + If you do not have <command>gdb</command> available, you + will have to check out your operating system's debugger. + </para> + </note> + </para> + <para> + You should mail the traceback to the + <ulink url="mailto:&EtherealDevMailList;">&EtherealDevMailList;</ulink> + mailing list. + </para> + </section> + + <section><title>Reporting Crashes on Windows platforms</title> + <para> + The Windows distributions don't contain the symbol files (.pdb), because + they are very large. For this reason it's not possible to create + a meaningful backtrace file from it. You should report your crash just + like other problems, using the mechanism described above. + </para> + </section> + </section> + +</chapter> +<!-- End of EUG Chapter 1 --> diff --git a/docbook/ug-src/EUG_chapter_io.xml b/docbook/ug-src/EUG_chapter_io.xml index b1d3668bbb..d0088cd459 100644 --- a/docbook/ug-src/EUG_chapter_io.xml +++ b/docbook/ug-src/EUG_chapter_io.xml @@ -1,761 +1,763 @@ -<!-- EUG Chapter IO -->
-<chapter id="ChapterIO">
- <title>File Input / Output and Printing</title>
-
- <section id="ChIOIntroductionSection"><title>Introduction</title>
- <para>
- This chapter will describe input and output of capture data.
- <itemizedlist>
- <listitem>
- <para>
- Open/Import capture files in various capture file formats
- </para>
- </listitem>
- <listitem>
- <para>
- Save/Export capture files in various capture file formats
- </para>
- </listitem>
- <listitem>
- <para>
- Merge capture files together
- </para>
- </listitem>
- <listitem>
- <para>
- Print packets
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </section>
-
- <section id="ChIOOpenSection"><title>Open capture files</title>
- <para>
- Ethereal can read in previously saved capture files.
- To read them, simply select the <command>Open</command>
- menu item from the <command>File</command> menu.
- Ethereal will then pop up the File
- Open dialog box, which is discussed in more detail in
- <xref linkend="ChIOOpen"/>.
- </para>
- <note><title>Note!</title>
- <para>
- You can also use <command>drag-and-drop </command> to open a file, by
- simply dropping the desired file from your file manager onto Ethereal's
- main window. However, drag-and-drop is not available/won't work in all
- desktop environments.
- </para>
- </note>
- <para>
- If you didn't save the current capture file before, you will be asked
- to do so, to prevent data loss (this behaviour can be disabled in the
- preferences).
- </para>
- <para>
- In addition to its native file format (libpcap format, also used by
- tcpdump/WinDump and other libpcap/WinPcap-based programs), Ethereal can
- read capture files from a large number of other packet capture programs
- as well. See <xref linkend="ChIOInputFormatsSection"/> for the list of
- capture formats Ethereal understands.
- </para>
-
- <section id="ChIOOpen"><title>The "Open Capture File" dialog box</title>
- <para>
- The "Open Capture File" dialog box allows you to search for a
- capture file containing previously captured packets for display in
- Ethereal. <xref linkend="ChIOOpenFileDialog"/> shows an example
- of the Ethereal Open File Dialog box.
- </para>
- <note>
- <title>Note</title>
- <para>
- Ethereal uses the open dialog box from the version of the GTK+
- toolkit that it's using. This dialog was completely redesigned in
- GTK version 2.4. Depending on the installed GTK version,
- your dialog box might look different. However, as the
- functionality remains almost the same, much of this description
- will work with your version of Ethereal.
- </para>
- </note>
- <figure id="ChIOOpenFileDialog">
- <title>The "Open Capture File" Dialog box</title>
- <graphic entityref="EtherealOpen" format="PNG"/>
- </figure>
- <para>
- With this dialog box, you can perform the following actions:
- <orderedlist>
- <listitem>
- <para>
- The "+ Add" button allows you to add a directory, selected in the
- right-hand pane, to the favorites (bookmarks?) list. Those changes
- are persistent.
- </para>
- </listitem>
- <listitem>
- <para>
- The "- Remove" button allows you to remove a selected directory from
- that list again (the items like: "Home", "Desktop", and "Filesystem"
- cannot be removed).
- </para>
- </listitem>
- <listitem>
- <para>
- Select files and directories with the list boxes.
- </para>
- </listitem>
- <listitem>
- <para>
- View file preview information (like the filesize, the number of
- packets, ...), while browsing the filesystem.
- </para>
- </listitem>
- <listitem>
- <para>
- Specify a display filter with the Filter button and filter
- field. This filter will be used when opening the new file.
- Clicking on the Filter button causes Ethereal to pop up
- the Filters dialog box (which is discussed further in
- <xref linkend="ChWorkDisplayFilterSection"/>).
- </para>
- </listitem>
- <listitem>
- <para>
- Specify which name resolution is to be performed for all packets by
- clicking on one of the "Enable name resolution" check buttons.
- Details about name resolution can be found in
- <xref linkend="ChAdvNameResolutionSection"/>.
- </para>
- </listitem>
- <listitem>
- <para>
- Click the Open button to accept your selected file and open it.
- If Ethereal doesn't recognize the capture format, it will grey out
- this button.
- </para>
- </listitem>
- <listitem>
- <para>
- Click the Cancel button to go back to Ethereal and not load a capture
- file.
- </para>
- </listitem>
- </orderedlist>
- You can change the display filter and name resolution settings later while
- viewing the packets. However, for very large capture files it can take a
- significant amount of time changing these settings, so it might be
- a good idea to set them in advance here.
- </para>
- </section>
-
- <section id="ChIOInputFormatsSection">
- <title>Input File Formats</title>
- <para>
- The following file formats from other capture tools can be opened by
- <application>Ethereal</application>:
- <itemizedlist>
- <listitem><para>libpcap, tcpdump and various other tools using tcpdump's capture format</para></listitem>
- <listitem><para>Sun snoop and atmsnoop</para></listitem>
- <listitem><para>Shomiti/Finisar <emphasis>Surveyor</emphasis> captures</para></listitem>
- <listitem><para>Novell <emphasis>LANalyzer</emphasis> captures</para></listitem>
- <listitem><para>Microsoft Network Monitor captures</para></listitem>
- <listitem><para>AIX's iptrace captures</para></listitem>
- <listitem><para>Cinco Networks NetXray captures</para></listitem>
- <listitem><para>Network Associates Windows-based Sniffer and Sniffer Pro captures</para></listitem>
- <listitem><para>Network General/Network Associates DOS-based Sniffer (compressed or unconpressed) captures</para></listitem>
- <listitem><para>AG Group/WildPackets EtherPeek/TokenPeek/AiroPeek/EtherHelp/PacketGrabber captures</para></listitem>
- <listitem><para>RADCOM's WAN/LAN Analyzer captures</para></listitem>
- <listitem><para>Network Instruments Observer version 9 captures</para></listitem>
- <listitem><para>Lucent/Ascend router debug output</para></listitem>
- <listitem><para>HP-UX's nettl</para></listitem>
- <listitem><para>Toshiba's ISDN routers dump output</para></listitem>
- <listitem><para>ISDN4BSD <emphasis>i4btrace</emphasis> utility</para></listitem>
- <listitem><para>traces from the EyeSDN USB S0</para></listitem>
- <listitem><para>IPLog format from the Cisco Secure Intrusion Detection System</para></listitem>
- <listitem><para>pppd logs (pppdump format)</para></listitem>
- <listitem><para>the output from VMS's TCPIPtrace/TCPtrace/UCX$TRACE utilities</para></listitem>
- <listitem><para>the text output from the DBS Etherwatch VMS utility</para></listitem>
- <listitem><para>Visual Networks' Visual UpTime traffic capture</para></listitem>
- <listitem><para>the output from CoSine L2 debug</para></listitem>
- <listitem><para>the output from Accellent's 5Views LAN agents</para></listitem>
- <listitem><para>Endace Measurement Systems' ERF format captures</para></listitem>
- <listitem><para>Linux Bluez Bluetooth stack hcidump -w traces</para></listitem>
- </itemizedlist>
- </para>
- <note><title>Note!</title>
- <para>
- It may not be possible to read some formats dependent on the packet types
- captured. Ethernet captures are usually supported for most file formats,
- but other packet types (e.g. token ring packets) may not be possible to
- read from all file formats.
- </para>
- </note>
-
- </section>
-
- </section>
-
- <section id="ChIOSaveSection"><title>Saving captured packets</title>
- <para>
- You can save captured packets simply by using the Save As... menu
- item from the File menu under Ethereal. You can choose which
- packets to save and which file format to be used.
- </para>
- <section id="ChIOSaveAs">
- <title>The "Save Capture File As" dialog box</title>
- <para>
- The "Save Capture File As" dialog box allows you to save
- the current capture to a file.
- <xref linkend="ChIOSaveCaptureFileAs"/> shows an example of this
- dialog box.
- </para>
- <note>
- <title>Note</title>
- <para>
- Ethereal uses the open dialog box from the version of the GTK+
- toolkit that it's using. This dialog was completely redesigned in
- the GTK version 2.4. Depending on the installed GTK version,
- your dialog box might look different. However, as the
- functionality remains almost the same, much of this description
- will work with your version of Ethereal.
- </para>
- </note>
- <figure id="ChIOSaveCaptureFileAs">
- <title>The "Save Capture File As" dialog box</title>
- <graphic entityref="EtherealSaveAs" format="PNG"/>
- </figure>
- <para>
- With this dialog box, you can perform the following actions:
- <orderedlist>
- <listitem>
- <para>
- Type in the name of the file you wish to save the captured
- packets in, as a standard file name in your file system.
- </para>
- </listitem>
- <listitem>
- <para>
- Select the directory to save the file into.
- </para>
- </listitem>
- <listitem>
- <para>
- Select the range of the packets to be saved, see
- <xref linkend="ChIOPacketRangeSection"/>
- </para>
- </listitem>
- <listitem>
- <para>
- Specify the format of the saved capture file by clicking on
- the File type drop down box. You can choose from the
- types, described in <xref linkend="ChIOInputFormatsSection"/>.
- </para>
- <note>
- <title>Note!</title>
- <para>
- Some capture formats may not be available, depending on the
- packet types captured.
- </para>
- </note>
- <tip>
- <title>Tip!</title>
- <para>
- You can convert capture files from one format to another
- by reading in a capture file and writing it out using a
- different format.
- </para>
- </tip>
- </listitem>
- <listitem>
- <para>
- Use "Browse for other folders" to browse files and folders in your
- file system.
- </para>
- </listitem>
- <listitem>
- <para>
- Click on the Save button to accept your selected file and save to
- it. If Ethereal has a problem saving the captured packets to
- the file you specified, it will display an error dialog box.
- After clicking OK on this error dialog box, you can try again.
- </para>
- </listitem>
- <listitem>
- <para>
- Click on the Cancel button to go back to Ethereal and not save the
- captured packets.
- </para>
- </listitem>
- </orderedlist>
- </para>
- </section>
- <section id="ChIOOutputFormatsSection">
- <title>Output File Formats</title>
- <para>
- The following file formats can be saved by <application>Ethereal</application>,
- so other capture tools can read the capture data from:
- <itemizedlist>
- <listitem><para>libpcap (tcpdump)</para></listitem>
- <listitem><para>Novell LANalyzer</para></listitem>
- <listitem><para>Network Associates Sniffer</para></listitem>
- <listitem><para>Sun snoop</para></listitem>
- <listitem><para>Microsoft Network Monitor</para></listitem>
- <listitem><para>Visual Networks Visual UpTime traffic</para></listitem>
- <listitem><para>Accellent 5Views</para></listitem>
- <listitem><para>Networks Instruments Observer version 9</para></listitem>
- </itemizedlist>
- </para>
- <note><title></title>
- <para>
- Other protocol analyzers may require that the file has a certain suffix
- in order to read the files you generate with Ethereal, e.g.:
- </para>
- <para>
- ".DMP" for Tcpdump/libpcap
- </para>
- <para>
- ".CAP" for Network Assosciates Sniffer Windows
- </para>
- </note>
- </section>
- </section>
-
- <section id="ChIOMergeSection"><title>Merging capture files</title>
- <para>
- Sometimes you need to merge several capture files into one. For example
- this can be useful, if you have captured simultaneously from multiple
- interfaces at once (e.g. using multiple instances of Ethereal).
- </para>
- <para>
- Merging capture files can be done in three ways:
- <itemizedlist>
- <listitem><para>
- Use the <command>menu item "Merge"</command> from the "File" menu,
- to open the merge dialog, see <xref linkend="ChIOMergeDialog"/>.
- </para></listitem>
- <listitem><para>
- Use <command>drag-and-drop</command> to drop multiple files on the
- main window. Ethereal will try to merge the packets in chronological
- order from the dropped files into a newly created temporary file.
- </para></listitem>
- <listitem><para>
- Use the <command>mergecap</command> tool, which is a command
- line tool to merge capture files. This tool provides the most options
- to merge capture files, see <xref linkend="AppToolsmergecap"/>.
- </para></listitem>
- </itemizedlist>
- </para>
- <section><title>The "Merge with Capture File" dialog box</title>
- <para>
- This dialog box let you select a file to be merged into the currently
- loaded file.
- </para>
- <note><title>Note!</title>
- <para>If your current data wasn't saved before, you will be asked to save
- it first, before this dialog box is shown.</para>
- </note>
- <figure id="ChIOMergeDialog">
- <title>The "Merge with Capture File" dialog box</title>
- <graphic entityref="EtherealMergeDialog" format="PNG"/>
- </figure>
- <variablelist>
- <varlistentry>
- <term><command>Prepend packets to existing file</command></term>
- <listitem>
- <para>
- Prepend the packets from the selected file before the currently loaded
- packets.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><command>Merge packets chronologically</command></term>
- <listitem>
- <para>
- Merge both the packets from the selected and currently loaded file in
- chronological order.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><command>Append packets to existing file</command></term>
- <listitem>
- <para>
- Append the packets from the selected file after the currently loaded
- packets.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- <para>
- All other controls will work the same way as in the "Open Capture File"
- dialog box, see <xref linkend="ChIOOpen"/>.
- </para>
- </section>
- </section>
-
- <section id="ChIOExportSection"><title>Exporting data</title>
- <para>
- Ethereal provides several ways and formats to export packet data. This
- section describes general ways to export data from Ethereal.
- </para>
- <note><title>Note!</title>
- <para>
- There are more specialized functions to export specific data,
- which will be described at the appropriate places.
- </para>
- </note>
- <para>
- XXX - add detailed descriptions of the output formats and some sample
- output, too.
- </para>
- <section id="ChIOExportPlainDialog">
- <title>The "Export as Plain Text File" dialog box</title>
- <para id="ChIOExportPlain">
- Export packet data into a plain ASCII text file, much like the format
- used to print packets.
- <figure>
- <title>The "Export as Plain Text File" dialog box</title>
- <graphic entityref="EtherealExportPlainDialog" format="PNG"/>
- </figure>
- <itemizedlist>
- <listitem><para>
- <command>Export to file:</command> frame chooses the file to export
- the packet data to.
- </para></listitem>
- <listitem><para>
- The <command>Packet Range</command> frame is described in <xref
- linkend="ChIOPacketRangeSection"/>.
- </para></listitem>
- <listitem><para>
- The <command>Packet Details</command> frame is described in <xref
- linkend="ChIOPacketFormatSection"/>.
- </para></listitem>
- </itemizedlist>
- </para>
- </section>
- <section id="ChIOExportPSDialog">
- <title>The "Export as PostScript File" dialog box</title>
- <para>
- Export packet data into PostScript, much like the format used
- to print packets.
- <tip><title>Tip!</title>
- <para>
- You can easily convert PostScript files to PDF files using ghostscript.
- For example: export to a file named foo.ps and then call:
- <command>ps2pdf foo.ps</command>
- </para>
- </tip>
- <figure>
- <title>The "Export as PostScript File" dialog box</title>
- <graphic entityref="EtherealExportPSDialog" format="PNG"/>
- </figure>
- <itemizedlist>
- <listitem><para>
- <command>Export to file:</command> frame chooses the file to export
- the packet data to.
- </para></listitem>
- <listitem><para>
- The <command>Packet Range</command> frame is described in <xref
- linkend="ChIOPacketRangeSection"/>.
- </para></listitem>
- <listitem><para>
- The <command>Packet Details</command> frame is described in <xref
- linkend="ChIOPacketFormatSection"/>.
- </para></listitem>
- </itemizedlist>
- </para>
- </section>
- <section id="ChIOExportPSMLDialog">
- <title>The "Export as PSML File" dialog box</title>
- <para>
- Export packet data into PSML. This is an XML based format including
- only the packet summary.
- <figure>
- <title>The "Export as PSML File" dialog box</title>
- <graphic entityref="EtherealExportPSMLDialog" format="PNG"/>
- </figure>
- <itemizedlist>
- <listitem><para>
- <command>Export to file:</command> frame chooses the file to export
- the packet data to.
- </para></listitem>
- <listitem><para>
- The <command>Packet Range</command> frame is described in <xref
- linkend="ChIOPacketRangeSection"/>.
- </para></listitem>
- </itemizedlist>
- There's no such thing as a packet details frame for PSML export, as the
- packet format is defined by the PSML specification.
- </para>
- </section>
- <section id="ChIOExportPDMLDialog">
- <title>The "Export as PDML File" dialog box</title>
- <para>
- Export packet data into PDML. This is an XML based format including
- the packet details. The PDML file specification is available at:
- <ulink url="http://analyzer.polito.it/30alpha/docs/dissectors/PDMLSpec.htm">
- PDML specification</ulink>.
- <note><title></title>
- <para>
- The PDML specification is not officially released and Ethereal's
- implementation of it is still in an early beta state, so please expect
- changes in future Ethereal versions.
- </para>
- </note>
- <figure>
- <title>The "Export as PDML File" dialog box</title>
- <graphic entityref="EtherealExportPDMLDialog" format="PNG"/>
- </figure>
- <itemizedlist>
- <listitem><para>
- <command>Export to file:</command> frame chooses the file to export
- the packet data to.
- </para></listitem>
- <listitem><para>
- The <command>Packet Range</command> frame is described in <xref
- linkend="ChIOPacketRangeSection"/>.
- </para></listitem>
- </itemizedlist>
- There's no such thing as a packet details frame for PDML export, as the
- packet format is defined by the PDML specification.
- </para>
- </section>
- <section id="ChIOExportSelectedDialog">
- <title>The "Export selected packet bytes" dialog box</title>
- <para>
- Export the bytes selected in the "Packet Bytes" pane into a raw
- binary file.
- <figure>
- <title>The "Export Selected Packet Bytes" dialog box</title>
- <graphic entityref="EtherealExportSelectedDialog" format="PNG"/>
- </figure>
- <itemizedlist>
- <listitem><para>
- <command>Name:</command> the filename to export the packet data to.
- </para></listitem>
- <listitem><para>
- The <command>Save in folder:</command> field lets you select the
- folder to save to (from some predefined folders).
- </para></listitem>
- <listitem><para>
- <command>Browse for other folders</command> provides a flexible
- way to choose a folder.
- </para></listitem>
- </itemizedlist>
- </para>
- </section>
- </section>
-
- <section id="ChIOPrintSection"><title>Printing packets</title>
- <para>
- To print packets, select the "Print..." menu item from the File menu.
- When you do this, Ethereal pops up the Print dialog box as shown in
- <xref linkend="ChIOPrintDialogBox"/>.
- </para>
- <section><title>The "Print" dialog box</title>
- <figure id="ChIOPrintDialogBox">
- <title>The "Print" dialog box</title>
- <graphic entityref="EtherealPrint" format="PNG"/>
- </figure>
- <para>
- The following fields are available in the Print dialog box:
- <variablelist>
- <varlistentry><term><command>Printer</command></term>
- <listitem>
- <para>
- This field contains a pair of mutually exclusive radio buttons:
- <itemizedlist>
- <listitem>
- <para>
- <command>Plain Text</command> specifies that
- the packet print should be in plain text.
- </para>
- </listitem>
- <listitem>
- <para>
- <command>PostScipt</command> specifies that
- the packet print process should use PostScript to
- generate a better print output on PostScript aware printers.
- </para>
- </listitem>
- <listitem>
- <para>
- <command>Output to file:</command> specifies that printing
- be done to a file, which name is entered in the field or selected
- using the browse button.
- </para>
- <para>
- This field is where you enter the <command>file</command> to
- print to if you have selected Print to a file, or you can click the
- button to browse the filesystem. It is greyed out if Print to a file
- is not selected.
- </para>
- </listitem>
- <listitem>
- <para>
- <command>Print command</command> specifies that a
- command be used for printing.
- </para>
- <note><title>Note!</title>
- <para>
- These <command>Print command</command> fields are not available on
- windows platforms.
- </para>
- </note>
- <para>
- This field specifies the command to use for printing. It
- is typically <command>lpr</command>. You would change it
- to specify a particular queue if you need to print to a
- queue other than the default. An example might be:
- <programlisting>
-lpr -Pmypostscript
- </programlisting>
- This field is greyed out if <command>Output to file:</command> is
- checked above.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><command>Packet Range</command></term>
- <listitem>
- <para>
- Select the packets to be printed, see <xref
- linkend="ChIOPacketRangeSection"/>
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><command>Packet Format</command></term>
- <listitem>
- <para>
- Select the output format of the packets to be printed. You can
- choose, how each packet is printed, see
- <xref linkend="ChIOPacketFormatFrame"/>
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
- </section>
- </section>
-
- <section id="ChIOPacketRangeSection"><title>The Packet Range frame</title>
- <para>
- The packet range frame is a part of various output related dialog boxes.
- It provides options to select which packets should be processed for the
- output function.
- <figure id="ChIOPacketRangeFrame">
- <title>The "Packet Range" frame</title>
- <graphic entityref="EtherealPacketRangeFrame" format="PNG"/>
- </figure>
- </para>
- <para>
- If the <command>Captured</command> button is set (default), all packets
- from the selected rule will be processed. If the <command>Displayed
- </command> button is set, only the currently displayed packets are taken
- into account to the selected rule.
- </para>
- <para>
- <itemizedlist>
- <listitem>
- <para>
- <command>All packets</command> will process all packets.
- </para>
- </listitem>
- <listitem>
- <para>
- <command>Selected packet only</command> process only the selected
- packet.
- </para>
- </listitem>
- <listitem>
- <para>
- <command>Marked packets only</command> process only the marked
- packets.
- </para>
- </listitem>
- <listitem>
- <para>
- <command>From first to last marked packet</command> process the
- packets from the first to the last marked one.
- </para>
- </listitem>
- <listitem>
- <para>
- <command>Specify a packet range</command> process a user specified
- range of packets, e.g. specifying <command>5,10-15,20-</command> will
- process the packet number five, the packets from packet number ten
- to fifteen (inclusive) and every packet from number twenty to the
- end of the capture.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </section>
-
- <section id="ChIOPacketFormatSection"><title>The Packet Format frame</title>
- <para>
- The packet format frame is a part of various output related dialog boxes.
- It provides options to select which parts of a packet should be used for
- the output function.
- <figure id="ChIOPacketFormatFrame">
- <title>The "Packet Format" frame</title>
- <graphic entityref="EtherealPacketFormatFrame" format="PNG"/>
- </figure>
- <itemizedlist>
- <listitem>
- <para>
- <command>Packet summary line</command> enable the output of the
- summary line, just as in the "Packet List" pane.
- </para>
- </listitem>
- <listitem>
- <para>
- <command>Packet details</command> enable the output of the packet
- details tree.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <command>All collapsed</command> the info from the "Packet Details"
- pane in "all collapsed" state.
- </para>
- </listitem>
- <listitem>
- <para>
- <command>As displayed</command> the info from the "Packet Details"
- pane in the current state.
- </para>
- </listitem>
- <listitem>
- <para>
- <command>All expanded</command> the info from the "Packet Details"
- pane in "all expanded" state.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- <listitem>
- <para>
- <command>Packet bytes</command> enable the output of the packet
- bytes, just as in the "Packet Bytes" pane.
- </para>
- </listitem>
- <listitem>
- <para>
- <command>Each packet on a new page</command> put each packet on a
- separate page (e.g. when saving/printing to a text file, this will
- put a form feed character between the packets).
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </section>
-
-</chapter>
-<!-- End of EUG Chapter IO -->
-
+<!-- EUG Chapter IO --> +<!-- $Id$ --> + +<chapter id="ChapterIO"> + <title>File Input / Output and Printing</title> + + <section id="ChIOIntroductionSection"><title>Introduction</title> + <para> + This chapter will describe input and output of capture data. + <itemizedlist> + <listitem> + <para> + Open/Import capture files in various capture file formats + </para> + </listitem> + <listitem> + <para> + Save/Export capture files in various capture file formats + </para> + </listitem> + <listitem> + <para> + Merge capture files together + </para> + </listitem> + <listitem> + <para> + Print packets + </para> + </listitem> + </itemizedlist> + </para> + </section> + + <section id="ChIOOpenSection"><title>Open capture files</title> + <para> + Ethereal can read in previously saved capture files. + To read them, simply select the <command>Open</command> + menu item from the <command>File</command> menu. + Ethereal will then pop up the File + Open dialog box, which is discussed in more detail in + <xref linkend="ChIOOpen"/>. + </para> + <note><title>Note!</title> + <para> + You can also use <command>drag-and-drop </command> to open a file, by + simply dropping the desired file from your file manager onto Ethereal's + main window. However, drag-and-drop is not available/won't work in all + desktop environments. + </para> + </note> + <para> + If you didn't save the current capture file before, you will be asked + to do so, to prevent data loss (this behaviour can be disabled in the + preferences). + </para> + <para> + In addition to its native file format (libpcap format, also used by + tcpdump/WinDump and other libpcap/WinPcap-based programs), Ethereal can + read capture files from a large number of other packet capture programs + as well. See <xref linkend="ChIOInputFormatsSection"/> for the list of + capture formats Ethereal understands. + </para> + + <section id="ChIOOpen"><title>The "Open Capture File" dialog box</title> + <para> + The "Open Capture File" dialog box allows you to search for a + capture file containing previously captured packets for display in + Ethereal. <xref linkend="ChIOOpenFileDialog"/> shows an example + of the Ethereal Open File Dialog box. + </para> + <note> + <title>Note</title> + <para> + Ethereal uses the open dialog box from the version of the GTK+ + toolkit that it's using. This dialog was completely redesigned in + GTK version 2.4. Depending on the installed GTK version, + your dialog box might look different. However, as the + functionality remains almost the same, much of this description + will work with your version of Ethereal. + </para> + </note> + <figure id="ChIOOpenFileDialog"> + <title>The "Open Capture File" Dialog box</title> + <graphic entityref="EtherealOpen" format="PNG"/> + </figure> + <para> + With this dialog box, you can perform the following actions: + <orderedlist> + <listitem> + <para> + The "+ Add" button allows you to add a directory, selected in the + right-hand pane, to the favorites (bookmarks?) list. Those changes + are persistent. + </para> + </listitem> + <listitem> + <para> + The "- Remove" button allows you to remove a selected directory from + that list again (the items like: "Home", "Desktop", and "Filesystem" + cannot be removed). + </para> + </listitem> + <listitem> + <para> + Select files and directories with the list boxes. + </para> + </listitem> + <listitem> + <para> + View file preview information (like the filesize, the number of + packets, ...), while browsing the filesystem. + </para> + </listitem> + <listitem> + <para> + Specify a display filter with the Filter button and filter + field. This filter will be used when opening the new file. + Clicking on the Filter button causes Ethereal to pop up + the Filters dialog box (which is discussed further in + <xref linkend="ChWorkDisplayFilterSection"/>). + </para> + </listitem> + <listitem> + <para> + Specify which name resolution is to be performed for all packets by + clicking on one of the "Enable name resolution" check buttons. + Details about name resolution can be found in + <xref linkend="ChAdvNameResolutionSection"/>. + </para> + </listitem> + <listitem> + <para> + Click the Open button to accept your selected file and open it. + If Ethereal doesn't recognize the capture format, it will grey out + this button. + </para> + </listitem> + <listitem> + <para> + Click the Cancel button to go back to Ethereal and not load a capture + file. + </para> + </listitem> + </orderedlist> + You can change the display filter and name resolution settings later while + viewing the packets. However, for very large capture files it can take a + significant amount of time changing these settings, so it might be + a good idea to set them in advance here. + </para> + </section> + + <section id="ChIOInputFormatsSection"> + <title>Input File Formats</title> + <para> + The following file formats from other capture tools can be opened by + <application>Ethereal</application>: + <itemizedlist> + <listitem><para>libpcap, tcpdump and various other tools using tcpdump's capture format</para></listitem> + <listitem><para>Sun snoop and atmsnoop</para></listitem> + <listitem><para>Shomiti/Finisar <emphasis>Surveyor</emphasis> captures</para></listitem> + <listitem><para>Novell <emphasis>LANalyzer</emphasis> captures</para></listitem> + <listitem><para>Microsoft Network Monitor captures</para></listitem> + <listitem><para>AIX's iptrace captures</para></listitem> + <listitem><para>Cinco Networks NetXray captures</para></listitem> + <listitem><para>Network Associates Windows-based Sniffer and Sniffer Pro captures</para></listitem> + <listitem><para>Network General/Network Associates DOS-based Sniffer (compressed or unconpressed) captures</para></listitem> + <listitem><para>AG Group/WildPackets EtherPeek/TokenPeek/AiroPeek/EtherHelp/PacketGrabber captures</para></listitem> + <listitem><para>RADCOM's WAN/LAN Analyzer captures</para></listitem> + <listitem><para>Network Instruments Observer version 9 captures</para></listitem> + <listitem><para>Lucent/Ascend router debug output</para></listitem> + <listitem><para>HP-UX's nettl</para></listitem> + <listitem><para>Toshiba's ISDN routers dump output</para></listitem> + <listitem><para>ISDN4BSD <emphasis>i4btrace</emphasis> utility</para></listitem> + <listitem><para>traces from the EyeSDN USB S0</para></listitem> + <listitem><para>IPLog format from the Cisco Secure Intrusion Detection System</para></listitem> + <listitem><para>pppd logs (pppdump format)</para></listitem> + <listitem><para>the output from VMS's TCPIPtrace/TCPtrace/UCX$TRACE utilities</para></listitem> + <listitem><para>the text output from the DBS Etherwatch VMS utility</para></listitem> + <listitem><para>Visual Networks' Visual UpTime traffic capture</para></listitem> + <listitem><para>the output from CoSine L2 debug</para></listitem> + <listitem><para>the output from Accellent's 5Views LAN agents</para></listitem> + <listitem><para>Endace Measurement Systems' ERF format captures</para></listitem> + <listitem><para>Linux Bluez Bluetooth stack hcidump -w traces</para></listitem> + </itemizedlist> + </para> + <note><title>Note!</title> + <para> + It may not be possible to read some formats dependent on the packet types + captured. Ethernet captures are usually supported for most file formats, + but other packet types (e.g. token ring packets) may not be possible to + read from all file formats. + </para> + </note> + + </section> + + </section> + + <section id="ChIOSaveSection"><title>Saving captured packets</title> + <para> + You can save captured packets simply by using the Save As... menu + item from the File menu under Ethereal. You can choose which + packets to save and which file format to be used. + </para> + <section id="ChIOSaveAs"> + <title>The "Save Capture File As" dialog box</title> + <para> + The "Save Capture File As" dialog box allows you to save + the current capture to a file. + <xref linkend="ChIOSaveCaptureFileAs"/> shows an example of this + dialog box. + </para> + <note> + <title>Note</title> + <para> + Ethereal uses the open dialog box from the version of the GTK+ + toolkit that it's using. This dialog was completely redesigned in + the GTK version 2.4. Depending on the installed GTK version, + your dialog box might look different. However, as the + functionality remains almost the same, much of this description + will work with your version of Ethereal. + </para> + </note> + <figure id="ChIOSaveCaptureFileAs"> + <title>The "Save Capture File As" dialog box</title> + <graphic entityref="EtherealSaveAs" format="PNG"/> + </figure> + <para> + With this dialog box, you can perform the following actions: + <orderedlist> + <listitem> + <para> + Type in the name of the file you wish to save the captured + packets in, as a standard file name in your file system. + </para> + </listitem> + <listitem> + <para> + Select the directory to save the file into. + </para> + </listitem> + <listitem> + <para> + Select the range of the packets to be saved, see + <xref linkend="ChIOPacketRangeSection"/> + </para> + </listitem> + <listitem> + <para> + Specify the format of the saved capture file by clicking on + the File type drop down box. You can choose from the + types, described in <xref linkend="ChIOInputFormatsSection"/>. + </para> + <note> + <title>Note!</title> + <para> + Some capture formats may not be available, depending on the + packet types captured. + </para> + </note> + <tip> + <title>Tip!</title> + <para> + You can convert capture files from one format to another + by reading in a capture file and writing it out using a + different format. + </para> + </tip> + </listitem> + <listitem> + <para> + Use "Browse for other folders" to browse files and folders in your + file system. + </para> + </listitem> + <listitem> + <para> + Click on the Save button to accept your selected file and save to + it. If Ethereal has a problem saving the captured packets to + the file you specified, it will display an error dialog box. + After clicking OK on this error dialog box, you can try again. + </para> + </listitem> + <listitem> + <para> + Click on the Cancel button to go back to Ethereal and not save the + captured packets. + </para> + </listitem> + </orderedlist> + </para> + </section> + <section id="ChIOOutputFormatsSection"> + <title>Output File Formats</title> + <para> + The following file formats can be saved by <application>Ethereal</application>, + so other capture tools can read the capture data from: + <itemizedlist> + <listitem><para>libpcap (tcpdump)</para></listitem> + <listitem><para>Novell LANalyzer</para></listitem> + <listitem><para>Network Associates Sniffer</para></listitem> + <listitem><para>Sun snoop</para></listitem> + <listitem><para>Microsoft Network Monitor</para></listitem> + <listitem><para>Visual Networks Visual UpTime traffic</para></listitem> + <listitem><para>Accellent 5Views</para></listitem> + <listitem><para>Networks Instruments Observer version 9</para></listitem> + </itemizedlist> + </para> + <note><title></title> + <para> + Other protocol analyzers may require that the file has a certain suffix + in order to read the files you generate with Ethereal, e.g.: + </para> + <para> + ".DMP" for Tcpdump/libpcap + </para> + <para> + ".CAP" for Network Assosciates Sniffer Windows + </para> + </note> + </section> + </section> + + <section id="ChIOMergeSection"><title>Merging capture files</title> + <para> + Sometimes you need to merge several capture files into one. For example + this can be useful, if you have captured simultaneously from multiple + interfaces at once (e.g. using multiple instances of Ethereal). + </para> + <para> + Merging capture files can be done in three ways: + <itemizedlist> + <listitem><para> + Use the <command>menu item "Merge"</command> from the "File" menu, + to open the merge dialog, see <xref linkend="ChIOMergeDialog"/>. + </para></listitem> + <listitem><para> + Use <command>drag-and-drop</command> to drop multiple files on the + main window. Ethereal will try to merge the packets in chronological + order from the dropped files into a newly created temporary file. + </para></listitem> + <listitem><para> + Use the <command>mergecap</command> tool, which is a command + line tool to merge capture files. This tool provides the most options + to merge capture files, see <xref linkend="AppToolsmergecap"/>. + </para></listitem> + </itemizedlist> + </para> + <section><title>The "Merge with Capture File" dialog box</title> + <para> + This dialog box let you select a file to be merged into the currently + loaded file. + </para> + <note><title>Note!</title> + <para>If your current data wasn't saved before, you will be asked to save + it first, before this dialog box is shown.</para> + </note> + <figure id="ChIOMergeDialog"> + <title>The "Merge with Capture File" dialog box</title> + <graphic entityref="EtherealMergeDialog" format="PNG"/> + </figure> + <variablelist> + <varlistentry> + <term><command>Prepend packets to existing file</command></term> + <listitem> + <para> + Prepend the packets from the selected file before the currently loaded + packets. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command>Merge packets chronologically</command></term> + <listitem> + <para> + Merge both the packets from the selected and currently loaded file in + chronological order. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command>Append packets to existing file</command></term> + <listitem> + <para> + Append the packets from the selected file after the currently loaded + packets. + </para> + </listitem> + </varlistentry> + </variablelist> + <para> + All other controls will work the same way as in the "Open Capture File" + dialog box, see <xref linkend="ChIOOpen"/>. + </para> + </section> + </section> + + <section id="ChIOExportSection"><title>Exporting data</title> + <para> + Ethereal provides several ways and formats to export packet data. This + section describes general ways to export data from Ethereal. + </para> + <note><title>Note!</title> + <para> + There are more specialized functions to export specific data, + which will be described at the appropriate places. + </para> + </note> + <para> + XXX - add detailed descriptions of the output formats and some sample + output, too. + </para> + <section id="ChIOExportPlainDialog"> + <title>The "Export as Plain Text File" dialog box</title> + <para id="ChIOExportPlain"> + Export packet data into a plain ASCII text file, much like the format + used to print packets. + <figure> + <title>The "Export as Plain Text File" dialog box</title> + <graphic entityref="EtherealExportPlainDialog" format="PNG"/> + </figure> + <itemizedlist> + <listitem><para> + <command>Export to file:</command> frame chooses the file to export + the packet data to. + </para></listitem> + <listitem><para> + The <command>Packet Range</command> frame is described in <xref + linkend="ChIOPacketRangeSection"/>. + </para></listitem> + <listitem><para> + The <command>Packet Details</command> frame is described in <xref + linkend="ChIOPacketFormatSection"/>. + </para></listitem> + </itemizedlist> + </para> + </section> + <section id="ChIOExportPSDialog"> + <title>The "Export as PostScript File" dialog box</title> + <para> + Export packet data into PostScript, much like the format used + to print packets. + <tip><title>Tip!</title> + <para> + You can easily convert PostScript files to PDF files using ghostscript. + For example: export to a file named foo.ps and then call: + <command>ps2pdf foo.ps</command> + </para> + </tip> + <figure> + <title>The "Export as PostScript File" dialog box</title> + <graphic entityref="EtherealExportPSDialog" format="PNG"/> + </figure> + <itemizedlist> + <listitem><para> + <command>Export to file:</command> frame chooses the file to export + the packet data to. + </para></listitem> + <listitem><para> + The <command>Packet Range</command> frame is described in <xref + linkend="ChIOPacketRangeSection"/>. + </para></listitem> + <listitem><para> + The <command>Packet Details</command> frame is described in <xref + linkend="ChIOPacketFormatSection"/>. + </para></listitem> + </itemizedlist> + </para> + </section> + <section id="ChIOExportPSMLDialog"> + <title>The "Export as PSML File" dialog box</title> + <para> + Export packet data into PSML. This is an XML based format including + only the packet summary. + <figure> + <title>The "Export as PSML File" dialog box</title> + <graphic entityref="EtherealExportPSMLDialog" format="PNG"/> + </figure> + <itemizedlist> + <listitem><para> + <command>Export to file:</command> frame chooses the file to export + the packet data to. + </para></listitem> + <listitem><para> + The <command>Packet Range</command> frame is described in <xref + linkend="ChIOPacketRangeSection"/>. + </para></listitem> + </itemizedlist> + There's no such thing as a packet details frame for PSML export, as the + packet format is defined by the PSML specification. + </para> + </section> + <section id="ChIOExportPDMLDialog"> + <title>The "Export as PDML File" dialog box</title> + <para> + Export packet data into PDML. This is an XML based format including + the packet details. The PDML file specification is available at: + <ulink url="http://analyzer.polito.it/30alpha/docs/dissectors/PDMLSpec.htm"> + PDML specification</ulink>. + <note><title></title> + <para> + The PDML specification is not officially released and Ethereal's + implementation of it is still in an early beta state, so please expect + changes in future Ethereal versions. + </para> + </note> + <figure> + <title>The "Export as PDML File" dialog box</title> + <graphic entityref="EtherealExportPDMLDialog" format="PNG"/> + </figure> + <itemizedlist> + <listitem><para> + <command>Export to file:</command> frame chooses the file to export + the packet data to. + </para></listitem> + <listitem><para> + The <command>Packet Range</command> frame is described in <xref + linkend="ChIOPacketRangeSection"/>. + </para></listitem> + </itemizedlist> + There's no such thing as a packet details frame for PDML export, as the + packet format is defined by the PDML specification. + </para> + </section> + <section id="ChIOExportSelectedDialog"> + <title>The "Export selected packet bytes" dialog box</title> + <para> + Export the bytes selected in the "Packet Bytes" pane into a raw + binary file. + <figure> + <title>The "Export Selected Packet Bytes" dialog box</title> + <graphic entityref="EtherealExportSelectedDialog" format="PNG"/> + </figure> + <itemizedlist> + <listitem><para> + <command>Name:</command> the filename to export the packet data to. + </para></listitem> + <listitem><para> + The <command>Save in folder:</command> field lets you select the + folder to save to (from some predefined folders). + </para></listitem> + <listitem><para> + <command>Browse for other folders</command> provides a flexible + way to choose a folder. + </para></listitem> + </itemizedlist> + </para> + </section> + </section> + + <section id="ChIOPrintSection"><title>Printing packets</title> + <para> + To print packets, select the "Print..." menu item from the File menu. + When you do this, Ethereal pops up the Print dialog box as shown in + <xref linkend="ChIOPrintDialogBox"/>. + </para> + <section><title>The "Print" dialog box</title> + <figure id="ChIOPrintDialogBox"> + <title>The "Print" dialog box</title> + <graphic entityref="EtherealPrint" format="PNG"/> + </figure> + <para> + The following fields are available in the Print dialog box: + <variablelist> + <varlistentry><term><command>Printer</command></term> + <listitem> + <para> + This field contains a pair of mutually exclusive radio buttons: + <itemizedlist> + <listitem> + <para> + <command>Plain Text</command> specifies that + the packet print should be in plain text. + </para> + </listitem> + <listitem> + <para> + <command>PostScipt</command> specifies that + the packet print process should use PostScript to + generate a better print output on PostScript aware printers. + </para> + </listitem> + <listitem> + <para> + <command>Output to file:</command> specifies that printing + be done to a file, which name is entered in the field or selected + using the browse button. + </para> + <para> + This field is where you enter the <command>file</command> to + print to if you have selected Print to a file, or you can click the + button to browse the filesystem. It is greyed out if Print to a file + is not selected. + </para> + </listitem> + <listitem> + <para> + <command>Print command</command> specifies that a + command be used for printing. + </para> + <note><title>Note!</title> + <para> + These <command>Print command</command> fields are not available on + windows platforms. + </para> + </note> + <para> + This field specifies the command to use for printing. It + is typically <command>lpr</command>. You would change it + to specify a particular queue if you need to print to a + queue other than the default. An example might be: + <programlisting> +lpr -Pmypostscript + </programlisting> + This field is greyed out if <command>Output to file:</command> is + checked above. + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command>Packet Range</command></term> + <listitem> + <para> + Select the packets to be printed, see <xref + linkend="ChIOPacketRangeSection"/> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command>Packet Format</command></term> + <listitem> + <para> + Select the output format of the packets to be printed. You can + choose, how each packet is printed, see + <xref linkend="ChIOPacketFormatFrame"/> + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </section> + </section> + + <section id="ChIOPacketRangeSection"><title>The Packet Range frame</title> + <para> + The packet range frame is a part of various output related dialog boxes. + It provides options to select which packets should be processed for the + output function. + <figure id="ChIOPacketRangeFrame"> + <title>The "Packet Range" frame</title> + <graphic entityref="EtherealPacketRangeFrame" format="PNG"/> + </figure> + </para> + <para> + If the <command>Captured</command> button is set (default), all packets + from the selected rule will be processed. If the <command>Displayed + </command> button is set, only the currently displayed packets are taken + into account to the selected rule. + </para> + <para> + <itemizedlist> + <listitem> + <para> + <command>All packets</command> will process all packets. + </para> + </listitem> + <listitem> + <para> + <command>Selected packet only</command> process only the selected + packet. + </para> + </listitem> + <listitem> + <para> + <command>Marked packets only</command> process only the marked + packets. + </para> + </listitem> + <listitem> + <para> + <command>From first to last marked packet</command> process the + packets from the first to the last marked one. + </para> + </listitem> + <listitem> + <para> + <command>Specify a packet range</command> process a user specified + range of packets, e.g. specifying <command>5,10-15,20-</command> will + process the packet number five, the packets from packet number ten + to fifteen (inclusive) and every packet from number twenty to the + end of the capture. + </para> + </listitem> + </itemizedlist> + </para> + </section> + + <section id="ChIOPacketFormatSection"><title>The Packet Format frame</title> + <para> + The packet format frame is a part of various output related dialog boxes. + It provides options to select which parts of a packet should be used for + the output function. + <figure id="ChIOPacketFormatFrame"> + <title>The "Packet Format" frame</title> + <graphic entityref="EtherealPacketFormatFrame" format="PNG"/> + </figure> + <itemizedlist> + <listitem> + <para> + <command>Packet summary line</command> enable the output of the + summary line, just as in the "Packet List" pane. + </para> + </listitem> + <listitem> + <para> + <command>Packet details</command> enable the output of the packet + details tree. + </para> + <itemizedlist> + <listitem> + <para> + <command>All collapsed</command> the info from the "Packet Details" + pane in "all collapsed" state. + </para> + </listitem> + <listitem> + <para> + <command>As displayed</command> the info from the "Packet Details" + pane in the current state. + </para> + </listitem> + <listitem> + <para> + <command>All expanded</command> the info from the "Packet Details" + pane in "all expanded" state. + </para> + </listitem> + </itemizedlist> + </listitem> + <listitem> + <para> + <command>Packet bytes</command> enable the output of the packet + bytes, just as in the "Packet Bytes" pane. + </para> + </listitem> + <listitem> + <para> + <command>Each packet on a new page</command> put each packet on a + separate page (e.g. when saving/printing to a text file, this will + put a form feed character between the packets). + </para> + </listitem> + </itemizedlist> + </para> + </section> + +</chapter> +<!-- End of EUG Chapter IO --> + diff --git a/docbook/ug-src/EUG_chapter_statistics.xml b/docbook/ug-src/EUG_chapter_statistics.xml index 7bf05f70c3..72966ef63e 100644 --- a/docbook/ug-src/EUG_chapter_statistics.xml +++ b/docbook/ug-src/EUG_chapter_statistics.xml @@ -1,495 +1,497 @@ -<!-- EUG Chapter Statistics -->
-<chapter id="ChStatistics">
- <title>Statistics</title>
- <section id="ChStatIntroduction">
- <title>Introduction</title>
- <para>
- Ethereal provides a wide range of network statistics.
- </para>
- <para>
- These statistics range
- from general information about the loaded capture file (like the number of
- captured packets), to statistics about specific protocols
- (e.g. statistics about the number of HTTP requests and responses captured).
- <itemizedlist>
- <listitem>
- <para>
- General statistics:
- </para>
- <itemizedlist>
- <listitem>
- <para><command>Summary</command> about the capture file.</para>
- </listitem>
- <listitem>
- <para><command>Protocol Hierarchy</command> of the captured packets.</para>
- </listitem>
- <listitem>
- <para><command>Endpoints</command> e.g. traffic to and from an IP
- addresses.</para>
- </listitem>
- <listitem>
- <para><command>Conversations</command> e.g. traffic between specific IP
- addresses.</para>
- </listitem>
- <listitem>
- <para><command>IO Graphs</command> visualizing the number of packets (or
- similar) in time.</para>
- </listitem>
- </itemizedlist>
- </listitem>
- <listitem>
- <para>
- Protocol specific statistics:
- </para>
- <itemizedlist>
- <listitem>
- <para><command>Service Response Time</command> between request and response
- of some protocols.</para>
- </listitem>
- <listitem>
- <para><command>Various other</command> protocol specific statistics.</para>
- </listitem>
- </itemizedlist>
- </listitem>
- </itemizedlist>
- <tip><title>Tip!</title>
- <para>
- The protocol specific statistics requires detailed knowledge about the
- specific protocol. Unless you are familiar with that protocol, statistics
- about it will be pretty hard to understand.
- </para>
- </tip>
- </para>
- </section>
-
- <section id="ChStatSummary">
- <title>The "Summary" window</title>
- <para>
- General statistics about the current capture file.
- </para>
- <figure><title>The "Summary" window</title>
- <graphic entityref="EtherealStatsSummary" format="PNG"/>
- </figure>
- <itemizedlist>
- <listitem>
- <para><command>File</command> general information about the capture file.
- </para>
- </listitem>
- <listitem>
- <para><command>Time</command> the timestamps when the first and the
- last packet were capturing (and the time between them).</para>
- </listitem>
- <listitem>
- <para><command>Capture</command> information from the time when the
- capture was done (only available if the packet data was captured from the
- network and not loaded from a file).</para>
- </listitem>
- <listitem>
- <para><command>Display</command> some display related information.</para>
- </listitem>
- <listitem>
- <para>
- <command>Traffic</command> some statistics of the network traffic seen.
- If a display filter is set, you will see values in both columns. The
- values in the <command>Captured</command> column will remain the same as
- before, while the values in the <command>Displayed</command> column will
- reflect the values corresponding to the packets shown in the display.
- </para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section id="ChStatHierarchy">
- <title>The "Protocol Hierarchy" window</title>
- <para>
- The protocol hierarchy of the captured packets.
- <figure><title>The "Protocol Hierarchy" window</title>
- <graphic entityref="EtherealStatsHierarchy" format="PNG"/>
- </figure>
- This is a tree of all the protocols in the capture. You can collapse or
- expand subtrees, by clicking on the plus / minus icons. By default, all
- trees are expanded.
- </para>
- <para>
- Each row contains the statistical values of one protocol.
- </para>
- <para>
- The following columns containing the statistical values are available:
- <itemizedlist>
- <listitem>
- <para><command>Protocol</command> this protocol's name</para>
- </listitem>
- <listitem>
- <para><command>% Packets</command> the percentage of protocol packets,
- relative to all packets in the capture</para>
- </listitem>
- <listitem>
- <para><command>Packets</command> the absolute number of packets of this
- protocol</para>
- </listitem>
- <listitem>
- <para><command>Bytes</command> the absolute number of bytes of this
- protocol</para>
- </listitem>
- <listitem>
- <para><command>MBit/s</command> the bandwidth of this protocol, relative
- to the capture time</para>
- </listitem>
- <listitem>
- <para>
- <command>End Packets</command> the absolute number of packets of this
- protocol (where this protocol were the highest protocol to decode)
- </para>
- </listitem>
- <listitem>
- <para>
- <command>End Bytes</command> the absolute number of bytes of this protocol
- (where this protocol were the highest protocol to decode)
- </para>
- </listitem>
- <listitem>
- <para>
- <command>End MBit/s</command> the bandwidth of this protocol, relative to
- the capture time (where this protocol were the highest protocol to decode)
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <note><title>Note!</title>
- <para>
- Packets will usually contain multiple protocols, so more than one protocol
- will be counted for each packet.
- Example: In the screenshot IP has 99,17% and TCP 85,83% (which is together
- much more than 100%).
- </para>
- </note>
- </section>
-
- <section id="ChStatEndpoints">
- <title>Endpoints</title>
- <para>
- Statistics of the endpoints captured.
- <tip><title>Tip!</title>
- <para>
- If you are looking for a feature other network tools call a <command>
- hostlist</command>, here is the right place to look. The list of
- Ethernet or IP endpoints is usually what you're looking for.
- </para>
- </tip>
- </para>
- <section id="ChStatEndpointDefinition"><title>What is an Endpoint?</title>
- <para>
- A network endpoint is the logical endpoint of separate protocol traffic of
- a specific protocol layer. The endpoint statistics of Ethereal will take
- the following endpoints into account:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <command>Ethernet</command> an Ethernet endpoint is identical to the
- Ethernet's MAC address.
- </para>
- </listitem>
- <listitem>
- <para>
- <command>Fibre Channel</command> XXX - insert info here.
- </para>
- </listitem>
- <listitem>
- <para>
- <command>FDDI</command> a FDDI endpoint is identical to the FDDI MAC
- address.
- </para>
- </listitem>
- <listitem>
- <para>
- <command>IPv4</command> an IP endpoint is identical to its IP address.
- </para>
- </listitem>
- <listitem>
- <para>
- <command>IPX</command> XXX - insert info here.
- </para>
- </listitem>
- <listitem>
- <para>
- <command>TCP</command> a TCP endpoint is a combination of the IP address
- and the TCP port used, so different TCP ports on the same IP address are
- different TCP endpoints.
- </para>
- </listitem>
- <listitem>
- <para>
- <command>Token Ring</command> a Token Ring endpoint is identical to the
- Token Ring MAC address.
- </para>
- </listitem>
- <listitem>
- <para>
- <command>UDP</command> a UDP endpoint is a combination of the IP address
- and the UDP port used, so different UDP ports on the same IP address are
- different UDP endpoints.
- </para>
- </listitem>
- </itemizedlist>
- <note><title>Broadcast / multicast endpoints</title>
- <para>
- Broadcast / multicast traffic will be shown separately as additional
- endpoints. Of course, as these endpoints are virtual endpoints, the real
- traffic will be received by all (multicast: some) of the listed unicast
- endpoints.
- </para>
- </note>
- </section>
- <section id="ChStatEndpointsWindow">
- <title>The "Endpoints" window</title>
- <para>
- This window shows statistics about the endpoints captured.
- </para>
- <figure><title>The "Endpoints" window</title>
- <graphic entityref="EtherealStatsEndpoints" format="PNG"/>
- </figure>
- <para>
- For each supported protocol, a tab is shown in this window.
- The tab labels shows the number of endpoints captured (e.g. the
- tab label "Ethernet: 5" tells you that five ethernet endpoints have been
- captured). If no endpoints of a specific protocol were captured, the tab
- label will be
- grayed out (although the related page can still be selected).
- </para>
- <para>
- Each row in the list shows the statistical values for exactly one endpoint.
- </para>
- <para>
- <command>Name resolution</command> will be done if selected in the window
- and if it is active for the specific protocol layer (MAC layer for the
- selected Ethernet endpoints page). As you might have noticed, the first
- row has a name
- resolution of the first three bytes "Netgear", the second row's address was
- resolved to an IP address (using ARP) and the third was resolved
- to a broadcast (unresolved this would still be: ff:ff:ff:ff:ff:ff), the last two
- Ethernet addresses remain unresolved.
- </para>
- <tip><title>Tip!</title>
- <para>
- This window will be updated frequently, so it will be useful, even if
- you open it before (or while) you are doing a live capture.
- </para>
- </tip>
- </section>
- <section id="ChStatEndpointListWindow">
- <title>The protocol specific "Endpoint List" windows</title>
- <para>
- Before the combined window described above was available, each of its
- pages were shown as separate windows. Even though the combined window is
- much more convenient to use, these separate windows are still
- available. The main reason is, they might process faster for
- very large capture files. However, as the functionality is exactly the
- same as in the combined window, they won't be discussed in detail here.
- </para>
- </section>
- </section>
-
- <section id="ChStatConversations">
- <title>Conversations</title>
- <para>
- Statistics of the captured conversations.
- </para>
- <section><title>What is a Conversation?</title>
- <para>
- A network conversation is the traffic between two specific endpoints. For
- example, an IP conversation is all the traffic between two IP addresses.
- The description of the known endpoint types can be found in
- <xref linkend="ChStatEndpointDefinition"/>.
- </para>
- </section>
- <section id="ChStatConversationsWindow"><title>The "Conversations" window</title>
- <para>
- Beside the list content, the conversations window work the same way as the
- endpoint ones, see <xref linkend="ChStatEndpointsWindow"/> for a
- description how it works.
- <figure><title>The "Conversations" window</title>
- <graphic entityref="EtherealStatsConversations" format="PNG"/>
- </figure>
- </para>
- </section>
- <section id="ChStatConversationListWindow">
- <title>The protocol specific "Conversation List" windows</title>
- <para>
- Before the combined window described above was available, each of its
- pages were shown as separate windows. Even though the combined window is
- much more convenient to use, these separate windows are still
- available. The main reason is, they might process faster for
- very large capture files. However, as the functionality is exactly the
- same as in the combined window, they won't be discussed in detail here.
- </para>
- </section>
- </section>
-
- <section id="ChStatIOGraphs">
- <title>The "IO Graphs" window</title>
- <para>
- User configurable graph of the captured network packets.
- </para>
- <para>
- You can define up to five differently colored graphs.
- </para>
-
- <figure><title>The "IO Graphs" window</title>
- <graphic entityref="EtherealStatsIOGraphs" format="PNG"/>
- </figure>
-
- <para>
- The user can configure the following things:
- <itemizedlist>
- <listitem>
- <para><command>Graphs</command>
- <itemizedlist>
- <listitem>
- <para>
- <command>Graph 1-5</command> enable the graph 1-5 (only graph 1 is enabled
- by default)
- </para>
- </listitem>
- <listitem>
- <para>
- <command>Color</command> the color of the graph (cannot be changed)
- </para>
- </listitem>
- <listitem>
- <para>
- <command>Filter:</command> a display filter for this graph (only the
- packets that pass this filter will be taken into account for that graph)
- </para>
- </listitem>
- <listitem>
- <para>
- <command>Style:</command> the style of the graph (Line/Impulse/FBar)
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
-
- <listitem>
- <para><command>X Axis</command>
- <itemizedlist>
- <listitem>
- <para>
- <command>Tick interval</command> an interval in x direction lasts
- (10/1/0.1/0.01/0.001 seconds)
- </para>
- </listitem>
- <listitem>
- <para>
- <command>Pixels per tick</command> use 10/5/2/1 pixels per tick interval
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
-
- <listitem>
- <para><command>Y Axis</command>
- <itemizedlist>
- <listitem>
- <para>
- <command>Unit</command> the unit for the y direction (Packets/Tick,
- Bytes/Tick, Advanced...)
- </para>
- </listitem>
- <listitem>
- <para>
- <command>Scale</command> the scale for the y unit
- (10,20,50,100,200,500,...)
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
-
- </itemizedlist>
- XXX - describe the Advanced feature.
- </para>
- </section>
-
- <section id="ChStatSRT">
- <title>Service Response Time</title>
- <para>
- The service response time is the time between a request and the
- corresponding response. This information is available for many protocols.
- </para>
- <para>
- Service response time statistics are currently available for the following
- protocols:
- <itemizedlist>
- <listitem>
- <para><command>DCE-RPC</command></para>
- </listitem>
- <listitem>
- <para><command>Fibre Channel</command></para>
- </listitem>
- <listitem>
- <para><command>ITU-T H.225 RAS</command></para>
- </listitem>
- <listitem>
- <para><command>LDAP</command></para>
- </listitem>
- <listitem>
- <para><command>MGCP</command></para>
- </listitem>
- <listitem>
- <para><command>ONC-RPC</command></para>
- </listitem>
- <listitem>
- <para><command>SMB</command></para>
- </listitem>
- </itemizedlist>
- As an example, the DCE-RPC service response time is described in more
- detail.
- <note><title>Note!</title>
- <para>
- The other Service Response Time windows will work the same way (or only
- sligthly different) compared to the following description.
- </para>
- </note>
- </para>
- <section id="ChStatSRTDceRpc">
- <title>The "Service Response Time DCE-RPC" window</title>
- <para>
- The service response time of DCE-RPC is the time between the request and
- the corresponding response.
- </para>
- <para>
- First of all, you have to select the DCE-RPC interface:
- </para>
- <figure><title>The "Compute DCE-RPC statistics" window</title>
- <graphic entityref="EtherealStatsSrtDcerpcFilter" format="PNG"/>
- </figure>
- <para>
- You can optionally set a display filter, to reduce the amount of packets.
- </para>
- <figure><title>The "DCE-RPC Statistic for ..." window</title>
- <graphic entityref="EtherealStatsSrtDcerpc" format="PNG"/>
- </figure>
- <para>
- Each row corresponds to a method of the interface selected (so the EPM
- interface in version 3 has 7 methods). For each
- method the number of calls, and the statistics of the SRT time is
- calculated.
- </para>
- </section>
- </section>
-
- <section id="ChStatXXX">
- <title>The protocol specific statistics windows</title>
- <para>
- The protocol specific statistics windows display detailed information
- of specific protocols and might be described in a later
- version of this document.
- </para>
- </section>
-
-</chapter>
-<!-- End of EUG Chapter Statistics -->
-
+<!-- EUG Chapter Statistics --> +<!-- $Id$ --> + +<chapter id="ChStatistics"> + <title>Statistics</title> + <section id="ChStatIntroduction"> + <title>Introduction</title> + <para> + Ethereal provides a wide range of network statistics. + </para> + <para> + These statistics range + from general information about the loaded capture file (like the number of + captured packets), to statistics about specific protocols + (e.g. statistics about the number of HTTP requests and responses captured). + <itemizedlist> + <listitem> + <para> + General statistics: + </para> + <itemizedlist> + <listitem> + <para><command>Summary</command> about the capture file.</para> + </listitem> + <listitem> + <para><command>Protocol Hierarchy</command> of the captured packets.</para> + </listitem> + <listitem> + <para><command>Endpoints</command> e.g. traffic to and from an IP + addresses.</para> + </listitem> + <listitem> + <para><command>Conversations</command> e.g. traffic between specific IP + addresses.</para> + </listitem> + <listitem> + <para><command>IO Graphs</command> visualizing the number of packets (or + similar) in time.</para> + </listitem> + </itemizedlist> + </listitem> + <listitem> + <para> + Protocol specific statistics: + </para> + <itemizedlist> + <listitem> + <para><command>Service Response Time</command> between request and response + of some protocols.</para> + </listitem> + <listitem> + <para><command>Various other</command> protocol specific statistics.</para> + </listitem> + </itemizedlist> + </listitem> + </itemizedlist> + <tip><title>Tip!</title> + <para> + The protocol specific statistics requires detailed knowledge about the + specific protocol. Unless you are familiar with that protocol, statistics + about it will be pretty hard to understand. + </para> + </tip> + </para> + </section> + + <section id="ChStatSummary"> + <title>The "Summary" window</title> + <para> + General statistics about the current capture file. + </para> + <figure><title>The "Summary" window</title> + <graphic entityref="EtherealStatsSummary" format="PNG"/> + </figure> + <itemizedlist> + <listitem> + <para><command>File</command> general information about the capture file. + </para> + </listitem> + <listitem> + <para><command>Time</command> the timestamps when the first and the + last packet were capturing (and the time between them).</para> + </listitem> + <listitem> + <para><command>Capture</command> information from the time when the + capture was done (only available if the packet data was captured from the + network and not loaded from a file).</para> + </listitem> + <listitem> + <para><command>Display</command> some display related information.</para> + </listitem> + <listitem> + <para> + <command>Traffic</command> some statistics of the network traffic seen. + If a display filter is set, you will see values in both columns. The + values in the <command>Captured</command> column will remain the same as + before, while the values in the <command>Displayed</command> column will + reflect the values corresponding to the packets shown in the display. + </para> + </listitem> + </itemizedlist> + </section> + + <section id="ChStatHierarchy"> + <title>The "Protocol Hierarchy" window</title> + <para> + The protocol hierarchy of the captured packets. + <figure><title>The "Protocol Hierarchy" window</title> + <graphic entityref="EtherealStatsHierarchy" format="PNG"/> + </figure> + This is a tree of all the protocols in the capture. You can collapse or + expand subtrees, by clicking on the plus / minus icons. By default, all + trees are expanded. + </para> + <para> + Each row contains the statistical values of one protocol. + </para> + <para> + The following columns containing the statistical values are available: + <itemizedlist> + <listitem> + <para><command>Protocol</command> this protocol's name</para> + </listitem> + <listitem> + <para><command>% Packets</command> the percentage of protocol packets, + relative to all packets in the capture</para> + </listitem> + <listitem> + <para><command>Packets</command> the absolute number of packets of this + protocol</para> + </listitem> + <listitem> + <para><command>Bytes</command> the absolute number of bytes of this + protocol</para> + </listitem> + <listitem> + <para><command>MBit/s</command> the bandwidth of this protocol, relative + to the capture time</para> + </listitem> + <listitem> + <para> + <command>End Packets</command> the absolute number of packets of this + protocol (where this protocol were the highest protocol to decode) + </para> + </listitem> + <listitem> + <para> + <command>End Bytes</command> the absolute number of bytes of this protocol + (where this protocol were the highest protocol to decode) + </para> + </listitem> + <listitem> + <para> + <command>End MBit/s</command> the bandwidth of this protocol, relative to + the capture time (where this protocol were the highest protocol to decode) + </para> + </listitem> + </itemizedlist> + </para> + <note><title>Note!</title> + <para> + Packets will usually contain multiple protocols, so more than one protocol + will be counted for each packet. + Example: In the screenshot IP has 99,17% and TCP 85,83% (which is together + much more than 100%). + </para> + </note> + </section> + + <section id="ChStatEndpoints"> + <title>Endpoints</title> + <para> + Statistics of the endpoints captured. + <tip><title>Tip!</title> + <para> + If you are looking for a feature other network tools call a <command> + hostlist</command>, here is the right place to look. The list of + Ethernet or IP endpoints is usually what you're looking for. + </para> + </tip> + </para> + <section id="ChStatEndpointDefinition"><title>What is an Endpoint?</title> + <para> + A network endpoint is the logical endpoint of separate protocol traffic of + a specific protocol layer. The endpoint statistics of Ethereal will take + the following endpoints into account: + </para> + <itemizedlist> + <listitem> + <para> + <command>Ethernet</command> an Ethernet endpoint is identical to the + Ethernet's MAC address. + </para> + </listitem> + <listitem> + <para> + <command>Fibre Channel</command> XXX - insert info here. + </para> + </listitem> + <listitem> + <para> + <command>FDDI</command> a FDDI endpoint is identical to the FDDI MAC + address. + </para> + </listitem> + <listitem> + <para> + <command>IPv4</command> an IP endpoint is identical to its IP address. + </para> + </listitem> + <listitem> + <para> + <command>IPX</command> XXX - insert info here. + </para> + </listitem> + <listitem> + <para> + <command>TCP</command> a TCP endpoint is a combination of the IP address + and the TCP port used, so different TCP ports on the same IP address are + different TCP endpoints. + </para> + </listitem> + <listitem> + <para> + <command>Token Ring</command> a Token Ring endpoint is identical to the + Token Ring MAC address. + </para> + </listitem> + <listitem> + <para> + <command>UDP</command> a UDP endpoint is a combination of the IP address + and the UDP port used, so different UDP ports on the same IP address are + different UDP endpoints. + </para> + </listitem> + </itemizedlist> + <note><title>Broadcast / multicast endpoints</title> + <para> + Broadcast / multicast traffic will be shown separately as additional + endpoints. Of course, as these endpoints are virtual endpoints, the real + traffic will be received by all (multicast: some) of the listed unicast + endpoints. + </para> + </note> + </section> + <section id="ChStatEndpointsWindow"> + <title>The "Endpoints" window</title> + <para> + This window shows statistics about the endpoints captured. + </para> + <figure><title>The "Endpoints" window</title> + <graphic entityref="EtherealStatsEndpoints" format="PNG"/> + </figure> + <para> + For each supported protocol, a tab is shown in this window. + The tab labels shows the number of endpoints captured (e.g. the + tab label "Ethernet: 5" tells you that five ethernet endpoints have been + captured). If no endpoints of a specific protocol were captured, the tab + label will be + grayed out (although the related page can still be selected). + </para> + <para> + Each row in the list shows the statistical values for exactly one endpoint. + </para> + <para> + <command>Name resolution</command> will be done if selected in the window + and if it is active for the specific protocol layer (MAC layer for the + selected Ethernet endpoints page). As you might have noticed, the first + row has a name + resolution of the first three bytes "Netgear", the second row's address was + resolved to an IP address (using ARP) and the third was resolved + to a broadcast (unresolved this would still be: ff:ff:ff:ff:ff:ff), the last two + Ethernet addresses remain unresolved. + </para> + <tip><title>Tip!</title> + <para> + This window will be updated frequently, so it will be useful, even if + you open it before (or while) you are doing a live capture. + </para> + </tip> + </section> + <section id="ChStatEndpointListWindow"> + <title>The protocol specific "Endpoint List" windows</title> + <para> + Before the combined window described above was available, each of its + pages were shown as separate windows. Even though the combined window is + much more convenient to use, these separate windows are still + available. The main reason is, they might process faster for + very large capture files. However, as the functionality is exactly the + same as in the combined window, they won't be discussed in detail here. + </para> + </section> + </section> + + <section id="ChStatConversations"> + <title>Conversations</title> + <para> + Statistics of the captured conversations. + </para> + <section><title>What is a Conversation?</title> + <para> + A network conversation is the traffic between two specific endpoints. For + example, an IP conversation is all the traffic between two IP addresses. + The description of the known endpoint types can be found in + <xref linkend="ChStatEndpointDefinition"/>. + </para> + </section> + <section id="ChStatConversationsWindow"><title>The "Conversations" window</title> + <para> + Beside the list content, the conversations window work the same way as the + endpoint ones, see <xref linkend="ChStatEndpointsWindow"/> for a + description how it works. + <figure><title>The "Conversations" window</title> + <graphic entityref="EtherealStatsConversations" format="PNG"/> + </figure> + </para> + </section> + <section id="ChStatConversationListWindow"> + <title>The protocol specific "Conversation List" windows</title> + <para> + Before the combined window described above was available, each of its + pages were shown as separate windows. Even though the combined window is + much more convenient to use, these separate windows are still + available. The main reason is, they might process faster for + very large capture files. However, as the functionality is exactly the + same as in the combined window, they won't be discussed in detail here. + </para> + </section> + </section> + + <section id="ChStatIOGraphs"> + <title>The "IO Graphs" window</title> + <para> + User configurable graph of the captured network packets. + </para> + <para> + You can define up to five differently colored graphs. + </para> + + <figure><title>The "IO Graphs" window</title> + <graphic entityref="EtherealStatsIOGraphs" format="PNG"/> + </figure> + + <para> + The user can configure the following things: + <itemizedlist> + <listitem> + <para><command>Graphs</command> + <itemizedlist> + <listitem> + <para> + <command>Graph 1-5</command> enable the graph 1-5 (only graph 1 is enabled + by default) + </para> + </listitem> + <listitem> + <para> + <command>Color</command> the color of the graph (cannot be changed) + </para> + </listitem> + <listitem> + <para> + <command>Filter:</command> a display filter for this graph (only the + packets that pass this filter will be taken into account for that graph) + </para> + </listitem> + <listitem> + <para> + <command>Style:</command> the style of the graph (Line/Impulse/FBar) + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + + <listitem> + <para><command>X Axis</command> + <itemizedlist> + <listitem> + <para> + <command>Tick interval</command> an interval in x direction lasts + (10/1/0.1/0.01/0.001 seconds) + </para> + </listitem> + <listitem> + <para> + <command>Pixels per tick</command> use 10/5/2/1 pixels per tick interval + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + + <listitem> + <para><command>Y Axis</command> + <itemizedlist> + <listitem> + <para> + <command>Unit</command> the unit for the y direction (Packets/Tick, + Bytes/Tick, Advanced...) + </para> + </listitem> + <listitem> + <para> + <command>Scale</command> the scale for the y unit + (10,20,50,100,200,500,...) + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + + </itemizedlist> + XXX - describe the Advanced feature. + </para> + </section> + + <section id="ChStatSRT"> + <title>Service Response Time</title> + <para> + The service response time is the time between a request and the + corresponding response. This information is available for many protocols. + </para> + <para> + Service response time statistics are currently available for the following + protocols: + <itemizedlist> + <listitem> + <para><command>DCE-RPC</command></para> + </listitem> + <listitem> + <para><command>Fibre Channel</command></para> + </listitem> + <listitem> + <para><command>ITU-T H.225 RAS</command></para> + </listitem> + <listitem> + <para><command>LDAP</command></para> + </listitem> + <listitem> + <para><command>MGCP</command></para> + </listitem> + <listitem> + <para><command>ONC-RPC</command></para> + </listitem> + <listitem> + <para><command>SMB</command></para> + </listitem> + </itemizedlist> + As an example, the DCE-RPC service response time is described in more + detail. + <note><title>Note!</title> + <para> + The other Service Response Time windows will work the same way (or only + sligthly different) compared to the following description. + </para> + </note> + </para> + <section id="ChStatSRTDceRpc"> + <title>The "Service Response Time DCE-RPC" window</title> + <para> + The service response time of DCE-RPC is the time between the request and + the corresponding response. + </para> + <para> + First of all, you have to select the DCE-RPC interface: + </para> + <figure><title>The "Compute DCE-RPC statistics" window</title> + <graphic entityref="EtherealStatsSrtDcerpcFilter" format="PNG"/> + </figure> + <para> + You can optionally set a display filter, to reduce the amount of packets. + </para> + <figure><title>The "DCE-RPC Statistic for ..." window</title> + <graphic entityref="EtherealStatsSrtDcerpc" format="PNG"/> + </figure> + <para> + Each row corresponds to a method of the interface selected (so the EPM + interface in version 3 has 7 methods). For each + method the number of calls, and the statistics of the SRT time is + calculated. + </para> + </section> + </section> + + <section id="ChStatXXX"> + <title>The protocol specific statistics windows</title> + <para> + The protocol specific statistics windows display detailed information + of specific protocols and might be described in a later + version of this document. + </para> + </section> + +</chapter> +<!-- End of EUG Chapter Statistics --> + diff --git a/docbook/ug-src/EUG_chapter_troubleshoot.xml b/docbook/ug-src/EUG_chapter_troubleshoot.xml index 411aeb8e36..b0afb9b251 100644 --- a/docbook/ug-src/EUG_chapter_troubleshoot.xml +++ b/docbook/ug-src/EUG_chapter_troubleshoot.xml @@ -1,127 +1,129 @@ -<!-- EUG Chapter Four -->
-<chapter id="Chap04">
- <title>Troubleshooting with <application>Ethereal</application></title>
- <section>
- <title>An approach to troubleshooting with Ethereal</title>
- <para>
- Ethereal is a very useful tool for network troubleshooting, since it
- contains a number of features that allow you to quickly focus on
- problems in your networkfor several reasons:
- <itemizedlist>
- <listitem>
- <para>
- It allows you to focus in on specific packets and protocols,
- as you can see a large amount of detail associated with
- various protocols.
- </para>
- </listitem>
- <listitem>
- <para>
- It supports a large number of protocols, and the list of
- protocols supported is growing as more people contribute
- dissectors
- </para>
- </listitem>
- <listitem>
- <para>
- By giving you a visual view of traffic in parts of your
- network, and providing tools to filter and colorize that
- information, you can get a better feel for your network
- traffic, and can understand your network better.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- The following general approach is suggested:
- <itemizedlist>
- <listitem>
- <para>
- Determine that the problem looks like a networking problem.
- There is no point in capturing packets if the problem is not
- networking related.
- </para>
- </listitem>
- <listitem>
- <para>
- Figure out where to capture packets. You will have to
- capture packets from a part of the network where you can
- actually get network traffic related to the problem. This is
- especially important in the presence of switches and routers.
- See <xref linkend="Ch04ROUSWI"/> for more details.
- </para>
- <para>
- Because Ethereal can read many capture file formats, you can
- capture using any conventient tool. One useful approach is
- to use <command>tcpdump</command> to capture on remote
- systems and then copy the capture file to your system for
- later analysis. For more details on capturing with
- <command>tcpdump</command>, see <xref linkend="Ch05tcpdump"/>.
- </para>
- </listitem>
- <listitem>
- <para>
- Once you have captured packets that you think relate to
- the problem, load them into Ethereal and look for your
- problem. Using Ethereal's filtering and colorization
- capabilities, you can quickly narrow down the capture to the
- area of interest.
- </para>
- </listitem>
- <listitem>
- <para>
- Examine the appropriate fields within the packets where
- the problem appears to be. These can often help to reveal
- the problem.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </section>
- <section id="Ch04ROUSWI">
- <title>Capturing in the presence of switches and routers</title>
- <para>
- In the old days of Ethernet, all network traffic was spreaded over one
- "yellow" cable through the whole network. Capturing data was easy,
- as all packets from the network could be captured using the
- "promiscuous mode" at any place in the network. The only devices blocking
- network traffic, were routers. But as routers were extremely expensive,
- they were not widely used.
- </para>
- <para>
- Then Ethernet wiring using hubs become the state of the art. As the hubs
- still spreaded the packets all over the network, things regarding
- capturing didn't changed.
- </para>
- <para>
- At the next stage, Ethernet switches became widely available. This
- complicated things a lot. When capturing traffic on a computer connected
- to a switch, usually the switch will only forward packets to the computer,
- which are directed to it, or to all computers (broadcast's). It's much the
- same like deactivating the promiscuous mode of the capturing network card.
- </para>
- <para>
- There are some ways to circumvent this.
- </para>
- <para>
- Many vendor's switches support a feature known as "port spanning"
- or "port mirroring" in which all of the traffic to and from port A
- are also sent out port B. An excellent reference on the
- "port spanning" feature of Cisco switches can be found at
- <ulink url="http://www.cisco.com/warp/public/473/41.html">
- Configuring the Catalyst Switched Port Analyzer (SPAN) Feature
- </ulink>
- </para>
- </section>
- <section>
- <title>Examples of troubleshooting</title>
- <para>
- Troubleshooting often requires a reasonable knowledge of the
- protocols in question. However, as Ethereal will often give you some
- good hints, you might get an idea of what is going wrong simply by
- looking in the packets being exchanged.
- </para>
- </section>
-</chapter>
-<!-- End of EUG Chapter 4 -->
-
+<!-- EUG Chapter Four --> +<!-- $Id$ --> + +<chapter id="Chap04"> + <title>Troubleshooting with <application>Ethereal</application></title> + <section> + <title>An approach to troubleshooting with Ethereal</title> + <para> + Ethereal is a very useful tool for network troubleshooting, since it + contains a number of features that allow you to quickly focus on + problems in your networkfor several reasons: + <itemizedlist> + <listitem> + <para> + It allows you to focus in on specific packets and protocols, + as you can see a large amount of detail associated with + various protocols. + </para> + </listitem> + <listitem> + <para> + It supports a large number of protocols, and the list of + protocols supported is growing as more people contribute + dissectors + </para> + </listitem> + <listitem> + <para> + By giving you a visual view of traffic in parts of your + network, and providing tools to filter and colorize that + information, you can get a better feel for your network + traffic, and can understand your network better. + </para> + </listitem> + </itemizedlist> + </para> + <para> + The following general approach is suggested: + <itemizedlist> + <listitem> + <para> + Determine that the problem looks like a networking problem. + There is no point in capturing packets if the problem is not + networking related. + </para> + </listitem> + <listitem> + <para> + Figure out where to capture packets. You will have to + capture packets from a part of the network where you can + actually get network traffic related to the problem. This is + especially important in the presence of switches and routers. + See <xref linkend="Ch04ROUSWI"/> for more details. + </para> + <para> + Because Ethereal can read many capture file formats, you can + capture using any conventient tool. One useful approach is + to use <command>tcpdump</command> to capture on remote + systems and then copy the capture file to your system for + later analysis. For more details on capturing with + <command>tcpdump</command>, see <xref linkend="Ch05tcpdump"/>. + </para> + </listitem> + <listitem> + <para> + Once you have captured packets that you think relate to + the problem, load them into Ethereal and look for your + problem. Using Ethereal's filtering and colorization + capabilities, you can quickly narrow down the capture to the + area of interest. + </para> + </listitem> + <listitem> + <para> + Examine the appropriate fields within the packets where + the problem appears to be. These can often help to reveal + the problem. + </para> + </listitem> + </itemizedlist> + </para> + </section> + <section id="Ch04ROUSWI"> + <title>Capturing in the presence of switches and routers</title> + <para> + In the old days of Ethernet, all network traffic was spreaded over one + "yellow" cable through the whole network. Capturing data was easy, + as all packets from the network could be captured using the + "promiscuous mode" at any place in the network. The only devices blocking + network traffic, were routers. But as routers were extremely expensive, + they were not widely used. + </para> + <para> + Then Ethernet wiring using hubs become the state of the art. As the hubs + still spreaded the packets all over the network, things regarding + capturing didn't changed. + </para> + <para> + At the next stage, Ethernet switches became widely available. This + complicated things a lot. When capturing traffic on a computer connected + to a switch, usually the switch will only forward packets to the computer, + which are directed to it, or to all computers (broadcast's). It's much the + same like deactivating the promiscuous mode of the capturing network card. + </para> + <para> + There are some ways to circumvent this. + </para> + <para> + Many vendor's switches support a feature known as "port spanning" + or "port mirroring" in which all of the traffic to and from port A + are also sent out port B. An excellent reference on the + "port spanning" feature of Cisco switches can be found at + <ulink url="http://www.cisco.com/warp/public/473/41.html"> + Configuring the Catalyst Switched Port Analyzer (SPAN) Feature + </ulink> + </para> + </section> + <section> + <title>Examples of troubleshooting</title> + <para> + Troubleshooting often requires a reasonable knowledge of the + protocols in question. However, as Ethereal will often give you some + good hints, you might get an idea of what is going wrong simply by + looking in the packets being exchanged. + </para> + </section> +</chapter> +<!-- End of EUG Chapter 4 --> + diff --git a/docbook/ug-src/EUG_chapter_use.xml b/docbook/ug-src/EUG_chapter_use.xml index ec85217f45..3d489b5052 100644 --- a/docbook/ug-src/EUG_chapter_use.xml +++ b/docbook/ug-src/EUG_chapter_use.xml @@ -1,1836 +1,1838 @@ -<!-- EUG Chapter Three -->
-<chapter id="ChapterUsing">
- <title>User Interface</title>
- <section id="ChUseIntroductionSection"><title>Introduction</title>
- <para>
- By now you have installed <application>Ethereal</application> and
- are most likely keen to get started capturing your first packets. In
- the next chapters we will explore:
- <itemizedlist>
- <listitem>
- <para>
- How the Ethereal user interface works
- </para>
- </listitem>
- <listitem>
- <para>
- How to capture packets in <application>Ethereal</application>
- </para>
- </listitem>
- <listitem>
- <para>
- How to view packets in <application>Ethereal</application>
- </para>
- </listitem>
- <listitem>
- <para>
- How to filter packets in <application>Ethereal</application>
- </para>
- </listitem>
- <listitem>
- <para>
- ... and many other things!
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </section>
-
- <section id="ChUseStartSection"><title>Start Ethereal</title>
- <para>
- You can start Ethereal from your shell or window manager.
- <tip><title>Tip!</title>
- <para>
- When starting Ethereal it's possible to specify optional settings using
- the command line. See <xref linkend="ChCustCommandLine"/> for details.
- </para>
- </tip>
- <note><title>Note!</title>
- <para>
- In the following chapters, a lot of screenshots from Ethereal will be shown.
- As Ethereal runs on many different platforms and there are different
- versions of the underlying GUI toolkit (GTK 1.x / 2.x) used, your
- screen might look different from the provided screenshots. But as there
- are no real differences in functionality, these screenshots should still
- be understandable.
- </para>
- </note>
- </para>
- </section>
-
- <section id="ChUseMainWindowSection"><title>The Main window</title>
- <para>
- Lets look at Ethereal's user interface. <xref linkend="ChUseFig01"/> shows
- Ethereal as you would usually see it after some packets captured or loaded
- (how to do this will be described later).
- <figure id="ChUseFig01">
- <title>The Main window</title>
- <graphic scale="100" entityref="EtherealThreePane1" format="PNG"/>
- </figure>
- </para>
- <para>
- Ethereal's main window consist of parts that are commonly known from many
- other GUI programs.
- <orderedlist>
- <listitem>
- <para>
- The <emphasis>menu</emphasis> (see <xref linkend="ChUseMenuSection"/>)
- is used to start actions.
- </para>
- </listitem>
- <listitem>
- <para>
- The <emphasis>main toolbar</emphasis> (see <xref linkend="ChUseMainToolbarSection"/>)
- provides quick access to frequently used items from the menu.
- </para>
- </listitem>
- <listitem>
- <para>
- The <emphasis>filter toolbar</emphasis> (see <xref linkend="ChUseFilterToolbarSection"/>)
- provides a way to directly manipulate the currently used display filter
- (see <xref linkend="ChWorkDisplayFilterSection"/>).
- </para>
- </listitem>
- <listitem>
- <para>
- The <emphasis>packet list pane</emphasis> (see <xref linkend="ChUsePacketListPaneSection"/>)
- displays a summary of each packet captured. By clicking on packets
- in this pane you control what is displayed in the other two panes.
- </para>
- </listitem>
- <listitem>
- <para>
- The <emphasis>packet details pane</emphasis> (see <xref linkend="ChUsePacketDetailsPaneSection"/>)
- displays the packet selected in the packet list pane in more detail.
- </para>
- </listitem>
- <listitem>
- <para>
- The <emphasis>packet bytes pane</emphasis> (see <xref linkend="ChUsePacketBytesPaneSection"/>)
- displays the data from the packet selected in the packet list pane, and
- highlights the field selected in the packet details pane.
- </para>
- </listitem>
- <listitem>
- <para>
- The <emphasis>statusbar</emphasis> (see <xref linkend="ChUseStatusbarSection"/>)
- shows some detailed information about the current program state and
- the captured data.
- </para>
- </listitem>
- </orderedlist>
- <tip><title>Tip!</title>
- <para>
- The layout of the main window can be customized by changing preference settings.
- See <xref linkend="ChCustGUILayoutPrefPage"/> for details!
- </para>
- </tip>
- </para>
- </section>
-
- <section id="ChUseMenuSection"><title>The Menu</title>
- <para>
- The Ethereal menu sits on top of the Ethereal window.
- An example is shown in <xref linkend="ChUseEtherealMenu"/>.
- </para>
- <note><title>Note!</title>
- <para>
- Menu items will be greyed out if the corresponding feature isn't
- available. For example, you cannot save a capture file if you didn't
- capture or load any data before.
- </para>
- </note>
- <para>
- <figure id="ChUseEtherealMenu"><title>The Menu</title>
- <graphic entityref="EtherealMenuOnly" format="PNG"/>
- </figure>
- </para>
- <para>
- It contains the following items:
- <variablelist>
- <varlistentry><term><command>File</command></term>
- <listitem>
- <para>
- This menu contains tems to open and merge capture files,
- save / print / export capture files in whole or in part,
- and to quit from Ethereal. See <xref linkend="ChUseFileMenuSection"/>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>Edit</command></term>
- <listitem>
- <para>
- This menu contains items to find a packet, time reference or mark one
- or more packets, set your preferences,
- (cut, copy, and paste are not presently implemented).
- See <xref linkend="ChUseEditMenuSection"/>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>View</command></term>
- <listitem>
- <para>This menu controls the display of the captured data,
- including the colorization of packets, zooming the font,
- show a packet in a separate window, expand and collapse trees in packet details, ....
- See <xref linkend="ChUseViewMenuSection"/>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>Go</command></term>
- <listitem>
- <para>This menu contains items to go to a specific packet.
- See <xref linkend="ChUseGoMenuSection"/>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>Capture</command></term>
- <listitem>
- <para>This menu allows you to start and stop captures and to edit capture filters.
- See <xref linkend="ChUseCaptureMenuSection"/>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>Analyze</command></term>
- <listitem>
- <para>
- This menu contains items to manipulate display filters, enable or
- disable the dissection of protocols, configure user specified decodes
- and follow a TCP stream.
- See <xref linkend="ChUseAnalyzeMenuSection"/>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>Statistics</command></term>
- <listitem>
- <para>
- This menu contains menu-items to display various statistic windows,
- including a summary of the packets that have been captured,
- display protocol hierarchy statistics and much more.
- See <xref linkend="ChUseStatisticsMenuSection"/>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>Help</command></term>
- <listitem>
- <para>
- This menu contains items to help the user, like access to some basic
- help, a list of the supported protocols, manual pages, online access
- to some of the webpages, and the usual about dialog.
- See <xref linkend="ChUseHelpMenuSection"/>.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- Each of these menu items is described in more detail in the sections
- that follow.
- </para>
- <tip><title>Tip!</title>
- <para>
- You can access menu items directly or by pressing the corresponding
- accelerator keys, which are shown at the right side of the
- menu. For example, you can press the Control (or Strg in german) and the K
- keys together to open the capture dialog.
- </para>
- </tip>
- </section>
-
- <section id="ChUseFileMenuSection"><title>The "File" menu</title>
- <para>
- The Ethereal file menu contains the fields shown in
- <xref linkend="ChUseTabFile"/>.
- </para>
- <figure id="ChUseEtherealFileMenu">
- <title>The "File" Menu</title>
- <graphic entityref="EtherealFileMenu" format="PNG"/>
- </figure>
- <table id="ChUseTabFile" frame="none"><title>File menu items</title>
- <tgroup cols="3">
- <colspec colnum="1" colwidth="72pt"/>
- <colspec colnum="2" colwidth="80pt"/>
- <thead>
- <row>
- <entry>Menu Item</entry>
- <entry>Accelerator</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><command>Open...</command></entry>
- <entry>Ctrl+O</entry>
- <entry><para>
- This menu item brings up the file open dialog box that
- allows you to load a capture file for viewing. It is
- discussed in more detail in <xref linkend="ChIOOpen"/>.
- </para></entry>
- </row>
- <row>
- <entry><command>Open Recent</command></entry>
- <entry></entry>
- <entry><para>
- This menu item shows a submenu containing the recently opened
- capture files. Clicking on one of the submenu items will open the
- corresponding capture file directly.
- </para></entry>
- </row>
- <row>
- <entry><command>Merge...</command></entry>
- <entry></entry>
- <entry><para>
- This menu item brings up the merge file dialog box that
- allows you to merge a capture file into the currently loaded one.
- It is discussed in more detail in <xref linkend="ChIOMergeSection"/>.
- </para></entry>
- </row>
- <row>
- <entry><command>Close</command></entry>
- <entry>Ctrl+W</entry>
- <entry><para>
- This menu item closes the current capture. If you
- haven't saved the capture, you will be asked to do so first
- (this can be disabled by a preference setting).
- </para></entry>
- </row>
- <row>
- <entry><command>------</command></entry>
- <entry></entry>
- <entry></entry>
- </row>
- <row>
- <entry><command>Save</command></entry>
- <entry>Ctrl+S</entry>
- <entry><para>
- This menu item saves the current capture. If you
- have not set a default capture file name (perhaps with
- the -w <capfile> option), Ethereal pops up the
- Save Capture File As dialog box (which is discussed
- further in <xref linkend="ChIOSaveAs"/>).
- </para><note>
- <title>Note!</title>
- <para>
- If you have already saved the current capture, this
- menu item will be greyed out.
- </para>
- </note><note>
- <title>Note!</title>
- <para>
- You cannot save a live capture while it is in
- progress. You must stop the capture in order to
- save.
- </para>
- </note></entry>
- </row>
- <row>
- <entry><command>Save As...</command></entry>
- <entry>Shift+Ctrl+S</entry>
- <entry><para>
- This menu item allows you to save the current capture
- file to whatever file you would like. It pops up the
- Save Capture File As dialog box (which is discussed
- further in <xref linkend="ChIOSaveAs"/>).
- </para></entry>
- </row>
- <row>
- <entry><command>------</command></entry>
- <entry></entry>
- <entry></entry>
- </row>
- <row>
- <entry><command>Export > as "Plain Text" file...</command></entry>
- <entry></entry>
- <entry><para>
- This menu item allows you to export all, or some, of the packets in
- the capture file to a plain ASCII text file.
- It pops up the Ethereal Export dialog box (which is discussed further in
- <xref linkend="ChIOExportPlainDialog"/>).
- </para></entry>
- </row>
- <row>
- <entry><command>Export > as "PostScript" file...</command></entry>
- <entry></entry>
- <entry><para>
- This menu item allows you to export the (or some) of the packets in
- the capture file to a PostScript file.
- It pops up the Ethereal Export dialog box (which is discussed further in
- <xref linkend="ChIOExportPSDialog"/>).
- </para></entry>
- </row>
- <row>
- <entry><command>Export > as "PSML" file...</command></entry>
- <entry></entry>
- <entry><para>
- This menu item allows you to export the (or some) of the packets in
- the capture file to a PSML (packet summary markup language) XML file.
- It pops up the Ethereal Export dialog box (which is discussed further in
- <xref linkend="ChIOExportPSMLDialog"/>).
- </para></entry>
- </row>
- <row>
- <entry><command>Export > as "PDML" file...</command></entry>
- <entry></entry>
- <entry><para>
- This menu item allows you to export the (or some) of the packets in
- the capture file to a PDML (packet details markup language) XML file.
- It pops up the Ethereal Export dialog box (which is discussed further in
- <xref linkend="ChIOExportPDMLDialog"/>).
- </para></entry>
- </row>
- <row>
- <entry><command>Export > Selected Packet Bytes...</command></entry>
- <entry>Ctrl+H</entry>
- <entry><para>
- This menu item allows you to export the currently selected bytes
- in the packet bytes pane to a binary file. It pops up the
- Ethereal Export dialog box (which is discussed further in
- <xref linkend="ChIOExportSelectedDialog"/>)
- </para></entry>
- </row>
- <row>
- <entry><command>------</command></entry>
- <entry></entry>
- <entry></entry>
- </row>
- <row>
- <entry><command>Print...</command></entry>
- <entry>Ctrl+P</entry>
- <entry><para>
- This menu item allows you to print all (or some of) the packets in
- the capture file. It pops up the Ethereal Print dialog
- box (which is discussed further in
- <xref linkend="ChIOPrintSection"/>).
- </para></entry>
- </row>
- <row>
- <entry><command>------</command></entry>
- <entry></entry>
- <entry></entry>
- </row>
- <row>
- <entry><command>Quit</command></entry>
- <entry>Ctrl+Q</entry>
- <entry><para>
- This menu item allows you to quit from Ethereal.
- Ethereal will ask to save your capture file if you haven't saved
- it before (this can be disabled by a preference setting).
- </para></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-
- <section id="ChUseEditMenuSection"><title>The "Edit" menu</title>
- <para>
- The Ethereal Edit menu contains the fields shown in
- <xref linkend="ChUseTabEdit"/>.
- </para>
- <figure id="ChUseEtherealEditMenu">
- <title>The "Edit" Menu</title>
- <graphic entityref="EtherealEditMenu" format="PNG"/>
- </figure>
- <table id="ChUseTabEdit" frame="none">
- <title>Edit menu items</title>
- <tgroup cols="3">
- <colspec colnum="1" colwidth="72pt"/>
- <colspec colnum="2" colwidth="80pt"/>
- <thead>
- <row>
- <entry>Menu Item</entry>
- <entry>Accelerator</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><command>Find Packet...</command></entry>
- <entry>Ctrl+F</entry>
- <entry><para>
- This menu item brings up a dialog box that allows you
- to find a packet by many criteria.
- There is further information on finding packets in
- <xref linkend="ChWorkFindPacketSection"/>.
- </para></entry>
- </row>
- <row>
- <entry><command>Find Next</command></entry>
- <entry>Ctrl+N</entry>
- <entry><para>
- This menu item tries to find the next packet matching the
- settings from "Find Packet...".
- </para></entry>
- </row>
- <row>
- <entry><command>Find Previous</command></entry>
- <entry>Ctrl+B</entry>
- <entry><para>
- This menu item tries to find the previous packet matching the
- settings from "Find Packet...".
- </para></entry>
- </row>
- <row>
- <entry><command>------</command></entry>
- <entry></entry>
- <entry></entry>
- </row>
- <row>
- <entry><command>Time Reference > Set Time Reference</command></entry>
- <entry>Ctrl+T</entry>
- <entry><para>
- This menu item set a time reference on the currently selected
- packet. See <xref linkend="ChWorkTimeReferencePacketSection"/> for more information
- about the time referenced packets.
- </para></entry>
- </row>
- <row>
- <entry><command>Time Reference > Find Next</command></entry>
- <entry></entry>
- <entry><para>
- This menu item tries to find the next time referenced packet.
- </para></entry>
- </row>
- <row>
- <entry><command>Time Reference > Find Previous</command></entry>
- <entry></entry>
- <entry><para>
- This menu item tries to find the previous time referenced packet.
- </para></entry>
- </row>
- <row>
- <entry><command>Mark Packet</command></entry>
- <entry>Ctrl+M</entry>
- <entry><para>
- This menu item "marks" the currently selected packet. See
- <xref linkend="ChWorkMarkPacketSection"/> for details.
- </para></entry>
- </row>
- <row>
- <entry><command>Mark All Packets</command></entry>
- <entry></entry>
- <entry><para>
- This menu item "marks" all packets.
- </para></entry>
- </row>
- <row>
- <entry><command>Unmark All Packets</command></entry>
- <entry></entry>
- <entry><para>This menu item "unmarks" all marked packets.
- </para></entry>
- </row>
- <row>
- <entry><command>------</command></entry>
- <entry></entry>
- <entry></entry>
- </row>
- <row>
- <entry><command>Preferences...</command></entry>
- <entry>Shift+Ctrl+P</entry>
- <entry><para>
- This menu item brings up a dialog box that allows
- you to set preferences for many parameters that control
- Ethereal. You can also save your preferences so Ethereal
- will use them the next time you start it. More detail
- is provided in <xref linkend="ChCustPreferencesSection"/>.
- </para></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-
- <section id="ChUseViewMenuSection"><title>The "View" menu</title>
- <para>
- The Ethereal View menu contains the fields shown in
- <xref linkend="ChUseTabView"/>.
- </para>
- <figure id="ChUseEtherealViewMenu">
- <title>The "View" Menu</title>
- <graphic entityref="EtherealViewMenu" format="PNG"/>
- </figure>
- <table id="ChUseTabView" frame="none">
- <title>View menu items</title>
- <tgroup cols="3">
- <colspec colnum="1" colwidth="72pt"/>
- <colspec colnum="2" colwidth="80pt"/>
- <thead>
- <row>
- <entry>Menu Item</entry>
- <entry>Accelerator</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><command>Main Toolbar</command></entry>
- <entry></entry>
- <entry><para>
- This menu item hides or shows the main toolbar, see
- <xref linkend="ChUseMainToolbarSection"/>.
- </para></entry>
- </row>
- <row>
- <entry><command>Filter Toolbar</command></entry>
- <entry></entry>
- <entry><para>
- This menu item hides or shows the filter toolbar, see
- <xref linkend="ChUseFilterToolbarSection"/>.
- </para></entry>
- </row>
- <row>
- <entry><command>Statusbar</command></entry>
- <entry></entry>
- <entry><para>
- This menu item hides or shows the statusbar, see
- <xref linkend="ChUseStatusbarSection"/>.
- </para></entry>
- </row>
- <row>
- <entry><command>------</command></entry>
- <entry></entry>
- <entry></entry>
- </row>
- <row>
- <entry><command>Packet List</command></entry>
- <entry></entry>
- <entry><para>
- This menu item hides or shows the packet list pane, see
- <xref linkend="ChUsePacketListPaneSection"/>.
- </para></entry>
- </row>
- <row>
- <entry><command>Packet Details</command></entry>
- <entry></entry>
- <entry><para>
- This menu item hides or shows the packet details pane, see
- <xref linkend="ChUsePacketDetailsPaneSection"/>.
- </para></entry>
- </row>
- <row>
- <entry><command>Packet Bytes</command></entry>
- <entry></entry>
- <entry><para>
- This menu item hides or shows the packet bytes pane, see
- <xref linkend="ChUsePacketBytesPaneSection"/>.
- </para></entry>
- </row>
- <row>
- <entry><command>------</command></entry>
- <entry></entry>
- <entry></entry>
- </row>
- <row>
- <entry><command>Time Display Format > Time of Day</command></entry>
- <entry></entry>
- <entry><para>
- Selecting this tells Ethereal to display time
- stamps in time of day format, see
- <xref linkend="ChWorkTimeFormatsSection"/>.
- <note><title>Note!</title>
- <para>
- The fields "Time of Day", "Date and Time of
- Day", "Seconds Since Beginning of Capture" and "Seconds Since
- Previous Packet" are mutually exclusive.
- </para>
- </note>
- </para></entry>
- </row>
- <row>
- <entry><command>Time Display Format > Date and Time of Day</command></entry>
- <entry></entry>
- <entry><para>
- Selecting this tells Ethereal to display the
- time stamps in date and time of day format, see
- <xref linkend="ChWorkTimeFormatsSection"/>.
- </para></entry>
- </row>
- <row>
- <entry><command>Time Display Format > Seconds Since Beginning of Capture</command></entry>
- <entry></entry>
- <entry><para>
- Selecting this tells Ethereal to display time
- stamps in seconds since beginning of capture format, see
- <xref linkend="ChWorkTimeFormatsSection"/>.
- </para></entry>
- </row>
- <row>
- <entry><command>Time Display Format > Seconds Since Previous Packet</command></entry>
- <entry></entry>
- <entry><para>
- Selecting this tells Ethereal to display time stamps in
- seconds since previous packet format, see
- <xref linkend="ChWorkTimeFormatsSection"/>.
- </para></entry>
- </row>
- <row>
- <entry><command>Name Resolution > Resolve Name</command></entry>
- <entry></entry>
- <entry><para>
- This item allows you to trigger a name resolve of the current packet
- only, see <xref linkend="ChAdvNameResolutionSection"/>.
- </para></entry>
- </row>
- <row>
- <entry><command>Name Resolution > Enable for MAC Layer</command></entry>
- <entry></entry>
- <entry><para>
- This item allows you to control whether or not
- Ethereal translates MAC addresses into names, see
- <xref linkend="ChAdvNameResolutionSection"/>.
- </para></entry>
- </row>
- <row>
- <entry><command>Name Resolution > Enable for Network Layer</command></entry>
- <entry></entry>
- <entry><para>
- This item allows you to control whether or not
- Ethereal translates network addresses into names, see
- <xref linkend="ChAdvNameResolutionSection"/>.
- </para></entry>
- </row>
- <row>
- <entry><command>Name Resolution > Enable for Transport Layer</command></entry>
- <entry></entry>
- <entry><para>
- This item allows you to control whether or not
- Ethereal translates transport addresses into names, see
- <xref linkend="ChAdvNameResolutionSection"/>.
- </para></entry>
- </row>
- <row>
- <entry><command>Auto Scroll in Live Capture</command></entry>
- <entry></entry>
- <entry><para>
- This item allows you to specify that Ethereal
- should scroll the packet list pane as new packets come
- in, so you are always looking at the last packet. If you
- do not specify this, Ethereal simply adds new packets onto
- the end of the list, but does not scroll the packet list
- pane.
- </para></entry>
- </row>
- <row>
- <entry><command>------</command></entry>
- <entry></entry>
- <entry></entry>
- </row>
- <row>
- <entry><command>Zoom In</command></entry>
- <entry>Ctrl++</entry>
- <entry><para>
- Zoom into the packet data (increase the font size).
- </para></entry>
- </row>
- <row>
- <entry><command>Zoom Out</command></entry>
- <entry>Ctrl+-</entry>
- <entry><para>
- Zoom out of the packet data (decrease the font size).
- </para></entry>
- </row>
- <row>
- <entry><command>Normal Size</command></entry>
- <entry>Ctrl+=</entry>
- <entry><para>
- Set zoom level back to 100% (set font size back to normal).
- </para></entry>
- </row>
- <row>
- <entry><command>------</command></entry>
- <entry></entry>
- <entry></entry>
- </row>
- <row>
- <entry><command>Collapse All</command></entry>
- <entry></entry>
- <entry><para>
- Ethereal keeps a list of all the protocol subtrees
- that are expanded, and uses it to ensure that the
- correct subtrees are expanded when you display a packet.
- This menu item collapses the tree view of all packets
- in the capture list.
- </para></entry>
- </row>
- <row>
- <entry><command>Expand All</command></entry>
- <entry></entry>
- <entry><para>
- This menu item expands all subtrees in all packets in
- the capture.
- </para></entry>
- </row>
- <row>
- <entry><command>Expand Tree</command></entry>
- <entry></entry>
- <entry><para>
- This menu item expands the currently selected subtree in the
- packet details tree.
- </para></entry>
- </row>
- <row>
- <entry><command>------</command></entry>
- <entry></entry>
- <entry></entry>
- </row>
- <row>
- <entry><command>Coloring Rules...</command></entry>
- <entry></entry>
- <entry><para>
- This menu item brings up a dialog box that allows you
- to color packets in the packet list pane according to
- filter expressions you choose. It can be very useful
- for spotting certain types of packets, see
- <xref linkend="ChCustColorizationSection"/>.
- </para></entry>
- </row>
- <row>
- <entry><command>------</command></entry>
- <entry></entry>
- <entry></entry>
- </row>
- <row>
- <entry><command>Show Packet in New Window</command></entry>
- <entry></entry>
- <entry><para>
- This menu item brings up the selected packet in a
- separate window. The separate window shows only the
- tree view and byte view panes.
- </para></entry>
- </row>
- <row>
- <entry><command>Reload</command></entry>
- <entry>Ctrl-R</entry>
- <entry><para>
- This menu item allows you to reload the current
- capture file.
- </para></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-
- <section id="ChUseGoMenuSection"><title>The "Go" menu</title>
- <para>
- The Ethereal Go menu contains the fields shown in
- <xref linkend="ChUseTabGo"/>.
- </para>
- <figure id="ChUseEtherealGoMenu">
- <title>The "Go" Menu</title>
- <graphic entityref="EtherealGoMenu" format="PNG"/>
- </figure>
- <table id="ChUseTabGo" frame="none">
- <title>Go menu items</title>
- <tgroup cols="3">
- <colspec colnum="1" colwidth="72pt"/>
- <colspec colnum="2" colwidth="80pt"/>
- <thead>
- <row>
- <entry>Menu Item</entry>
- <entry>Accelerator</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><command>Go to Packet...</command></entry>
- <entry>Ctrl-G</entry>
- <entry><para>
- This menu item brings up a dialog box that allows you
- to specify a packet number, and then goes to that packet. See
- <xref linkend="ChWorkGoToPacketSection"/> for details.
- </para></entry>
- </row>
- <row>
- <entry><command>Go to Corresponding Packet</command></entry>
- <entry></entry>
- <entry><para>
- This menu item goes to the corresponding packet of the currently
- selected protocol field. If the selected field doesn't correspond
- to a packet, this item is greyed out.
- </para></entry>
- </row>
- <row>
- <entry><command>------</command></entry>
- <entry></entry>
- <entry></entry>
- </row>
- <row>
- <entry><command>First Packet</command></entry>
- <entry></entry>
- <entry><para>
- This menu item jumps to the first packet of the capture file.
- </para></entry>
- </row>
- <row>
- <entry><command>Last Packet</command></entry>
- <entry></entry>
- <entry><para>
- This menu item jumps to the last packet of the capture file.
- </para></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-
- <section id="ChUseCaptureMenuSection"><title>The "Capture" menu</title>
- <para>
- The Ethereal Capture menu contains the fields shown in
- <xref linkend="ChUseTabCap"/>.
- </para>
- <figure id="ChUseEtherealCaptureMenu">
- <title>The "Capture" Menu</title>
- <graphic entityref="EtherealCaptureMenu" format="PNG"/>
- </figure>
- <table id="ChUseTabCap" frame="none">
- <title>Capture menu items</title>
- <tgroup cols="3">
- <colspec colnum="1" colwidth="72pt"/>
- <colspec colnum="2" colwidth="80pt"/>
- <thead>
- <row>
- <entry>Menu Item</entry>
- <entry>Accelerator</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><command>Start...</command></entry>
- <entry>Ctrl+K</entry>
- <entry><para>
- This menu item brings up the Capture Options
- dialog box (discussed further in
- <xref linkend="ChCapCaptureOptions"/>) and allows you to
- start capturing packets.
- </para></entry>
- </row>
- <row>
- <entry><command>Stop</command></entry>
- <entry>Ctrl+E</entry>
- <entry><para>
- This menu item stops the currently running capture, see
- <xref linkend="ChCapStopSection"/>) .
- </para></entry>
- </row>
- <row>
- <entry><command>Capture Filters...</command></entry>
- <entry></entry>
- <entry><para>
- This menu item brings up a dialog box that allows you to
- create and edit capture filters. You can name filters,
- and you can save them for future use. More detail on
- this subject is provided in
- <xref linkend="ChWorkDefineFilterSection"/>
- </para></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-
- <section id="ChUseAnalyzeMenuSection"><title>The "Analyze" menu</title>
- <para>
- The Ethereal Analyze menu contains the fields shown in
- <xref linkend="ChUseAnalyze"/>.
- </para>
- <figure id="ChUseEtherealAnalyzeMenu">
- <title>The "Analyze" Menu</title>
- <graphic entityref="EtherealAnalyzeMenu" format="PNG"/>
- </figure>
- <table id="ChUseAnalyze" frame="none"><title>Analyze menu items</title>
- <tgroup cols="3">
- <colspec colnum="1" colwidth="72pt"/>
- <colspec colnum="2" colwidth="80pt"/>
- <thead>
- <row>
- <entry>Menu Item</entry>
- <entry>Accelerator</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><command>Display Filters...</command></entry>
- <entry></entry>
- <entry><para>
- This menu item brings up a dialog box that allows you
- to create and edit display filters. You can name
- filters, and you can save them for future use. More
- detail on this subject is provided in
- <xref linkend="ChWorkDefineFilterSection"/>
- </para></entry>
- </row>
- <row>
- <entry><command>Apply as Filter > ...</command></entry>
- <entry></entry>
- <entry><para>
- These menu items will change the current display filter and apply
- the changed filter immediately. Depending on the chosen menu item,
- the current display filter string will be replaced or appended to
- by the selected protocol field in the packet details pane.
- </para></entry>
- </row>
- <row>
- <entry><command>Prepare a Filter > ...</command></entry>
- <entry></entry>
- <entry><para>
- These menu items will change the current display filter but won't
- apply the changed filter. Depending on the chosen menu item,
- the current display filter string will be replaced or appended to
- by the selected protocol field in the packet details pane.
- </para></entry>
- </row>
- <row>
- <entry><command>------</command></entry>
- <entry></entry>
- <entry></entry>
- </row>
- <row>
- <entry><command>Enabled Protocols...</command></entry>
- <entry>Shift+Ctrl+R</entry>
- <entry><para>
- This menu item allows the user to enable/disable protocol
- dissectors, see <xref linkend="ChAdvEnabledProtocols"/>
- </para></entry>
- </row>
- <row>
- <entry><command>Decode As...</command></entry>
- <entry></entry>
- <entry><para>
- This menu item allows the user to force Ethereal to
- decode certain packets as a particular protocol, see
- <xref linkend="ChAdvDecodeAs"/>
- </para></entry>
- </row>
- <row>
- <entry><command>User Specified Decodes...</command></entry>
- <entry></entry>
- <entry><para>
- This menu item allows the user to force Ethereal to
- decode certain packets as a particular protocol, see
- <xref linkend="ChAdvDecodeAsShow"/>
- </para></entry>
- </row>
- <row>
- <entry><command>------</command></entry>
- <entry></entry>
- <entry></entry>
- </row>
- <row>
- <entry><command>Follow TCP Stream</command></entry>
- <entry></entry>
- <entry><para>
- This menu item brings up a separate window and displays
- all the TCP segments captured that are on the same TCP
- connection as a selected packet, see
- <xref linkend="ChAdvFollowTCPSection"/>
- </para></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-
- <section id="ChUseStatisticsMenuSection"><title>The "Statistics" menu</title>
- <para>
- The Ethereal Statistics menu contains the fields shown in
- <xref linkend="ChUseStatistics"/>.
- </para>
- <figure id="ChUseEtherealStatisticsMenu">
- <title>The "Statistics" Menu</title>
- <graphic entityref="EtherealStatisticsMenu" format="PNG"/>
- </figure>
- <para>
- All menu items will bring up a new window showing specific statistical
- information.
- </para>
- <table id="ChUseStatistics" frame="none">
- <title>Statistics menu items</title>
- <tgroup cols="3">
- <colspec colnum="1" colwidth="72pt"/>
- <colspec colnum="2" colwidth="80pt"/>
- <thead>
- <row>
- <entry>Menu Item</entry>
- <entry>Accelerator</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><command>Summary</command></entry>
- <entry></entry>
- <entry><para>
- Show information about the data captured, see <xref
- linkend="ChStatSummary"/>.
- </para></entry>
- </row>
- <row>
- <entry><command>Protocol Hierarchy</command></entry>
- <entry></entry>
- <entry><para>
- Display a hierarchical tree of protocol statistics, see <xref
- linkend="ChStatHierarchy"/>.
- </para></entry>
- </row>
- <row>
- <entry><command>Conversations</command></entry>
- <entry></entry>
- <entry><para>
- Display a list of conversations (traffic between two endpoints),
- see <xref linkend="ChStatConversationsWindow"/>.
- </para></entry>
- </row>
- <row>
- <entry><command>Endpoints</command></entry>
- <entry></entry>
- <entry><para>
- Display a list of endpoints (traffic to/from an address), see
- <xref linkend="ChStatEndpointsWindow"/>.
- </para></entry>
- </row>
- <row>
- <entry><command>IO Graphs</command></entry>
- <entry></entry>
- <entry><para>
- Display user specified graphs (e.g. the number of packets in the
- course of time), see <xref linkend="ChStatIOGraphs"/>.
- </para></entry>
- </row>
- <row>
- <entry><command>------</command></entry>
- <entry></entry>
- <entry></entry>
- </row>
- <row>
- <entry><command>Conversation List</command></entry>
- <entry></entry>
- <entry><para>
- Display a list of conversations, obsoleted by the combined window
- of Conversations above, see
- <xref linkend="ChStatConversationListWindow"/>.
- </para></entry>
- </row>
- <row>
- <entry><command>Endpoint List</command></entry>
- <entry></entry>
- <entry><para>
- Display a list of endpoints, obsoleted by the combined window
- of Endpoints above, see
- <xref linkend="ChStatEndpointListWindow"/>.
- </para></entry>
- </row>
- <row>
- <entry><command>Service Response Time</command></entry>
- <entry></entry>
- <entry><para>
- Display the time between a request and the corresponding response, see
- <xref linkend="ChStatSRT"/>.
- </para></entry>
- </row>
- <row>
- <entry><command>------</command></entry>
- <entry></entry>
- <entry></entry>
- </row>
- <row>
- <entry><command>ANSI</command></entry>
- <entry></entry>
- <entry><para>See <xref linkend="ChStatXXX"/></para></entry>
- </row>
- <row>
- <entry><command>BOOTP-DHCP</command></entry>
- <entry></entry>
- <entry><para>See <xref linkend="ChStatXXX"/></para></entry>
- </row>
- <row>
- <entry><command>GSM</command></entry>
- <entry></entry>
- <entry><para>See <xref linkend="ChStatXXX"/></para></entry>
- </row>
- <row>
- <entry><command>HTTP</command></entry>
- <entry></entry>
- <entry><para>HTTP request/response statistics, see <xref linkend="ChStatXXX"/></para></entry>
- </row>
- <row>
- <entry><command>ISUP Message Types</command></entry>
- <entry></entry>
- <entry><para>See <xref linkend="ChStatXXX"/></para></entry>
- </row>
- <row>
- <entry><command>ITU-T H.225</command></entry>
- <entry></entry>
- <entry><para>See <xref linkend="ChStatXXX"/></para></entry>
- </row>
- <row>
- <entry><command>MTP3</command></entry>
- <entry></entry>
- <entry><para>See <xref linkend="ChStatXXX"/></para></entry>
- </row>
- <row>
- <entry><command>ONC-RPC Programs</command></entry>
- <entry></entry>
- <entry><para>See <xref linkend="ChStatXXX"/></para></entry>
- </row>
- <row>
- <entry><command>RTP</command></entry>
- <entry></entry>
- <entry><para>See <xref linkend="ChStatXXX"/></para></entry>
- </row>
- <row>
- <entry><command>SIP</command></entry>
- <entry></entry>
- <entry><para>See <xref linkend="ChStatXXX"/></para></entry>
- </row>
- <row>
- <entry><command>TCP Stream Graph</command></entry>
- <entry></entry>
- <entry><para>See <xref linkend="ChStatXXX"/></para></entry>
- </row>
- <row>
- <entry><command>WAP-WSP</command></entry>
- <entry></entry>
- <entry><para>See <xref linkend="ChStatXXX"/></para></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-
- <section id="ChUseHelpMenuSection"><title>The "Help" menu</title>
- <para>
- The Ethereal Help menu contains the fields shown in
- <xref linkend="ChUseHelp"/>.
- </para>
- <figure id="ChUseEtherealHelpMenu">
- <title>The "Help" Menu</title>
- <graphic entityref="EtherealHelpMenu" format="PNG"/>
- </figure>
- <table id="ChUseHelp" frame="none">
- <title>Help menu items</title>
- <tgroup cols="3">
- <colspec colnum="1" colwidth="72pt"/>
- <colspec colnum="2" colwidth="80pt"/>
- <thead>
- <row>
- <entry>Menu Item</entry>
- <entry>Accelerator</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><command>Contents</command></entry>
- <entry>F1</entry>
- <entry><para>
- This menu item brings up a basic help system.
- </para></entry>
- </row>
- <row>
- <entry><command>Supported Protocols</command></entry>
- <entry></entry>
- <entry><para>
- This menu item brings up a dialog box showing the supported
- protocols and protocol fields.
- </para></entry>
- </row>
- <row>
- <entry><command>Manual Pages > ...</command></entry>
- <entry></entry>
- <entry><para>
- This menu item starts a Web browser showing one of the locally
- installed html manual pages.
- </para></entry>
- </row>
- <row>
- <entry><command>Ethereal Online > ...</command></entry>
- <entry></entry>
- <entry><para>
- This menu item tries to start a Web browser showing a specific
- webpage from:
- <ulink url="&EtherealWebSite;">&EtherealWebSite;</ulink>.
- </para></entry>
- </row>
- <row>
- <entry><command>------</command></entry>
- <entry></entry>
- <entry></entry>
- </row>
- <row>
- <entry><command>About Ethereal</command></entry>
- <entry></entry>
- <entry><para>
- This menu item brings up an information window that
- provides some information on Ethereal, such as the plugins, the
- used folders, ...
- </para></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-
- <section id="ChUseMainToolbarSection"><title>The "Main" toolbar</title>
- <para>
- The main toolbar provides quick access to frequently used items from the
- menu. This toolbar cannot be customized by the user, but it can be hidden
- using the View menu, if the space on the screen is needed to show even
- more packet data.
- </para>
- <para>
- As in the menu, only the items useful in the current program state will
- be available. The others will be greyed out (e.g. you cannot save a capture
- file if you haven't loaded one).
- <figure id="ChUseEtherealMainToolbar">
- <title>The "Main" toolbar</title>
- <graphic entityref="EtherealMainToolbar" format="PNG"/>
- </figure>
- </para>
- <table id="ChUseMainToolbar" frame="none">
- <title>Main toolbar items</title>
- <tgroup cols="4">
- <colspec colnum="1" colwidth="40pt"/>
- <colspec colnum="2" colwidth="80pt"/>
- <colspec colnum="3" colwidth="80pt"/>
- <thead>
- <row>
- <entry>Toolbar Icon</entry>
- <entry>Toolbar Item</entry>
- <entry>Corresponding Menu Item</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><graphic entityref="EtherealToolbarCapture" format="PNG"/></entry>
- <entry><command>Start Capture...</command></entry>
- <entry>Capture/Start...</entry>
- <entry><para>
- This item brings up the Capture Options
- dialog box (discussed further in
- <xref linkend="ChCapCapturingSection"/>) and allows you to
- start capturing packets.
- </para>
- <note><title>Note!</title>
- <para>
- If a live capture is in progress, and you are using "Update List
- of Packets in Realtime", this icon will be replaced by the Stop
- Capture icon
- <inlinegraphic entityref="EtherealToolbarStop" format="PNG"/>.
- </para></note>
- </entry>
- </row>
- <row>
- <entry><graphic entityref="EtherealToolbarStop" format="PNG"/></entry>
- <entry><command>Stop Capture</command></entry>
- <entry>Capture/Stop</entry>
- <entry><para>
- This item stops the currently running live capture process
- <xref linkend="ChCapCapturingSection"/>).
- </para>
- <note><title>Note!</title>
- <para>
- This icon is shown if a live capture is in progress, and you are
- using "Update List of Packets in Realtime", otherwise the Start
- Capture icon
- <inlinegraphic entityref="EtherealToolbarCapture" format="PNG"/>
- is shown.
- </para></note>
- </entry>
- </row>
- <row>
- <entry><command>------</command></entry>
- <entry></entry>
- <entry></entry>
- </row>
- <row>
- <entry><graphic entityref="EtherealToolbarOpen" format="PNG"/></entry>
- <entry><command>Open...</command></entry>
- <entry>File/Open...</entry>
- <entry><para>
- This item brings up the file open dialog box that
- allows you to load a capture file for viewing. It is
- discussed in more detail in <xref linkend="ChIOOpen"/>.
- </para></entry>
- </row>
- <row>
- <entry><graphic entityref="EtherealToolbarSaveAs" format="PNG"/></entry>
- <entry><command>Save As...</command></entry>
- <entry>File/Save As...</entry>
- <entry><para>
- This item allows you to save the current capture file to whatever
- file you would like. It pops up the Save Capture File As dialog
- box (which is discussed further in <xref linkend="ChIOSaveAs"/>).
- </para>
- <note><title>Note!</title>
- <para>
- If you currently have a temporary capture file, the Save icon
- <inlinegraphic entityref="EtherealToolbarSave" format="PNG"/> will be
- shown instead.
- </para></note>
- </entry>
- </row>
- <row>
- <entry><graphic entityref="EtherealToolbarClose" format="PNG"/></entry>
- <entry><command>Close</command></entry>
- <entry>File/Close</entry>
- <entry><para>
- This item closes the current capture. If you
- have not saved the capture, you will be asked to save it first.
- </para></entry>
- </row>
- <row>
- <entry><graphic entityref="EtherealToolbarReload" format="PNG"/></entry>
- <entry><command>Reload</command></entry>
- <entry>View/Reload</entry>
- <entry><para>
- This item allows you to reload the current capture file.
- </para></entry>
- </row>
- <row>
- <entry><graphic entityref="EtherealToolbarPrint" format="PNG"/></entry>
- <entry><command>Print...</command></entry>
- <entry>File/Print...</entry>
- <entry><para>
- This item allows you to print all (or some of) the packets in
- the capture file. It pops up the Ethereal Print dialog
- box (which is discussed further in
- <xref linkend="ChIOPrintSection"/>).
- </para></entry>
- </row>
- <row>
- <entry><command>------</command></entry>
- <entry></entry>
- <entry></entry>
- </row>
- <row>
- <entry><graphic entityref="EtherealToolbarFind" format="PNG"/></entry>
- <entry><command>Find Packet...</command></entry>
- <entry>Edit/Find Packet...</entry>
- <entry><para>
- This item brings up a dialog box that allows you
- to find a packet. There is further information on finding packets
- in <xref linkend="ChWorkFindPacketSection"/>.
- </para></entry>
- </row>
- <row>
- <entry><graphic entityref="EtherealToolbarFindPrevious" format="PNG"/></entry>
- <entry><command>Find Previous</command></entry>
- <entry>Edit/Find Previous</entry>
- <entry><para>
- This item tries to find the previous packet, matching the
- settings from "Find Packet...".
- </para></entry>
- </row>
- <row>
- <entry><graphic entityref="EtherealToolbarFindNext" format="PNG"/></entry>
- <entry><command>Find Next</command></entry>
- <entry>Edit/Find Next</entry>
- <entry><para>
- This item tries to find the next packet, matching the
- settings from "Find Packet...".
- </para></entry>
- </row>
- <row>
- <entry><command>------</command></entry>
- <entry></entry>
- <entry></entry>
- </row>
- <row>
- <entry><graphic entityref="EtherealToolbarGoTo" format="PNG"/></entry>
- <entry><command>Go to Packet...</command></entry>
- <entry>Go/Go to Packet...</entry>
- <entry><para>
- This item brings up a dialog box that allows you
- to specify a packet number to go to that packet.
- </para></entry>
- </row>
- <row>
- <entry><graphic entityref="EtherealToolbarGoFirst" format="PNG"/></entry>
- <entry><command>Go To First Packet</command></entry>
- <entry>Go/First Packet</entry>
- <entry><para>
- This item jumps to the first packet of the capture file.
- </para></entry>
- </row>
- <row>
- <entry><graphic entityref="EtherealToolbarGoLast" format="PNG"/></entry>
- <entry><command>Go To Last Packet</command></entry>
- <entry>Go/Last Packet</entry>
- <entry><para>
- This item jumps to the last packet of the capture file.
- </para></entry>
- </row>
- <row>
- <entry><command>------</command></entry>
- <entry></entry>
- <entry></entry>
- </row>
- <row>
- <entry><graphic entityref="EtherealToolbarZoomIn" format="PNG"/></entry>
- <entry><command>Zoom In</command></entry>
- <entry>View/Zoom In</entry>
- <entry><para>
- Zoom into the packet data (increase the font size).
- </para></entry>
- </row>
- <row>
- <entry><graphic entityref="EtherealToolbarZoomOut" format="PNG"/></entry>
- <entry><command>Zoom Out</command></entry>
- <entry>View/Zoom Out</entry>
- <entry><para>
- Zoom out of the packet data (decrease the font size).
- </para></entry>
- </row>
- <row>
- <entry><graphic entityref="EtherealToolbarZoom100" format="PNG"/></entry>
- <entry><command>Normal Size</command></entry>
- <entry>View/Normal Size</entry>
- <entry><para>
- Set zoom level back to 100%.
- </para></entry>
- </row>
- <row>
- <entry><command>------</command></entry>
- <entry></entry>
- <entry></entry>
- </row>
- <row>
- <entry><graphic entityref="EtherealToolbarCaptureFilters" format="PNG"/></entry>
- <entry><command>Capture Filters...</command></entry>
- <entry>Capture/Capture Filters...</entry>
- <entry><para>
- This item brings up a dialog box that allows you to
- create and edit capture filters. You can name filters,
- and you can save them for future use. More detail on
- this subject is provided in
- <xref linkend="ChWorkDefineFilterSection"/>.
- </para></entry>
- </row>
- <row>
- <entry><graphic entityref="EtherealToolbarDisplayFilters" format="PNG"/></entry>
- <entry><command>Display Filters...</command></entry>
- <entry>Analyze/Display Filters...</entry>
- <entry><para>
- This item brings up a dialog box that allows you
- to create and edit display filters. You can name
- filters, and you can save them for future use. More
- detail on this subject is provided in
- <xref linkend="ChWorkDefineFilterSection"/>.
- </para></entry>
- </row>
- <row>
- <entry><graphic entityref="EtherealToolbarColoringRules" format="PNG"/></entry>
- <entry><command>Coloring Rules...</command></entry>
- <entry>View/Coloring Rules...</entry>
- <entry><para>
- This item brings up a dialog box that allows you
- color packets in the packet list pane according to
- filter expressions you choose. It can be very useful
- for spotting certain types of packets. More
- detail on this subject is provided in
- <xref linkend="ChCustColorizationSection"/>.
- </para></entry>
- </row>
- <row>
- <entry><graphic entityref="EtherealToolbarPreferences" format="PNG"/></entry>
- <entry><command>Preferences...</command></entry>
- <entry>Edit/Preferences</entry>
- <entry><para>
- This item brings up a dialog box that allows
- you to set preferences for many parameters that control
- Ethereal. You can also save your preferences so Ethereal
- will use them the next time you start it. More detail
- is provided in <xref linkend="ChCustPreferencesSection"/>
- </para></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-
- <section id="ChUseFilterToolbarSection"><title>The "Filter" toolbar</title>
- <para>
- The filter toolbar lets you quickly edit and apply display filters. More information on
- display filters is available in <xref linkend="ChWorkDisplayFilterSection"/>.
- <figure id="ChUseEtherealFilterToolbar">
- <title>The "Filter" toolbar</title>
- <graphic entityref="EtherealFilterToolbar" format="PNG"/>
- </figure>
- <itemizedlist>
- <listitem>
- <para>
- The leftmost button labeled "Filter:" can be clicked to
- bring up the filter construction dialog, described in <xref linkend="FiltersDialog"/>.
- </para>
- </listitem>
- <listitem>
- <para>
- The left middle text box provides an area to enter or edit display
- filter strings, see <xref linkend="ChWorkBuildDisplayFilterSection"/>
- . A syntax check of your filter string is done while you are typing.
- The background will turn red if you enter an incomplete or invalid
- string, and will become green when you enter a valid string. You can
- click on the pull down arrow to select a previously-entered filter
- string from a list. The entries in the pull down list will remain
- available even after a program restart.
- </para>
- <note><title>Note!</title>
- <para>
- After you've changed something in this field, don't forget to press
- the Apply button (or the Enter/Return key), to apply this filter
- string to the display.
- </para>
- </note>
- <note><title>Note!</title>
- <para>
- This field is also where the current filter in effect is displayed.
- </para>
- </note>
- </listitem>
- <listitem>
- <para>
- The middle button labeled "Add Expression..." opens a dialog box that lets
- you edit a display filter from a list of protocol fields, described in
- <xref linkend="ChWorkFilterAddExpressionSection"/>
- </para>
- </listitem>
- <listitem>
- <para>
- The right middle button labeled "Clear" resets the current
- display filter and clears the edit area.
- </para>
- </listitem>
- <listitem>
- <para>
- The rightmost button labeled "Apply" applies the current
- value in the edit area as the new display filter.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <note><title>Note!</title>
- <para>
- Applying a display filter on large capture files might take quite a long time!
- </para>
- </note>
- </section>
-
- <section id="ChUsePacketListPaneSection"><title>The "Packet List" pane</title>
- <para>
- The packet list pane displays all the packets in the current capture
- file.
- <figure id="ChUseEtherealListPane">
- <title>The "Packet List" pane</title>
- <graphic entityref="EtherealListPane" format="PNG"/>
- </figure>
- Each line in the packet list corrresponds to one packet in the capture
- file. If you select a line in this pane, more details will be displayed in
- the "Packet Details" and "Packet Bytes" panes.
- </para>
- <para>
- While dissecting a packet, Ethereal will place information from the
- protocol dissectors into the columns. As higher level protocols might
- overwrite information from lower levels, you will typically see the
- information from the highest possible level only.
- </para>
- <para>
- For example, let's look at a packet containing TCP inside IP inside
- an Ethernet packet. The Ethernet dissector will write its data (such as
- the Ethernet addresses), the IP dissector will overwrite this by its own
- (such as the IP addresses), the TCP dissector will overwrite the IP
- information, and so on.
- </para>
- <para>
- There are a lot of different columns available. Which columns are
- displayed can be selected by preference settings, see
- <xref linkend="ChCustGUIColumnsPrefPage"/>.
- </para>
- <para>
- The default columns will show:
- <itemizedlist>
- <listitem>
- <para><command>No.</command>
- The number of the packet in the capture file. This number won't change,
- even if a display filter is used.
- </para>
- </listitem>
- <listitem>
- <para><command>Time</command>
- The timestamp of the packet. The presentation format of this timestamp
- can be changed, see <xref linkend="ChWorkTimeFormatsSection"/>.
- </para>
- </listitem>
- <listitem>
- <para><command>Source</command>
- The address where this packet is coming from.
- </para>
- </listitem>
- <listitem>
- <para><command>Destination</command>
- The address where this packet is going to.
- </para>
- </listitem>
- <listitem>
- <para><command>Protocol</command>
- The protocol name in a short (perhaps abbreviated) version.
- </para>
- </listitem>
- <listitem>
- <para><command>Info</command>
- Additional information about the packet content.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- There is a context menu (right mouse click) available, see details in
- <xref linkend="ChWorkPacketListPanePopUpMenu"/>.
- </para>
- </section>
-
- <section id="ChUsePacketDetailsPaneSection"><title>The "Packet Details" pane</title>
- <para>
- The packet details pane shows the current packet (selected in the "Packet List"
- pane) in a more detailed form.
- <figure id="ChUseEtherealDetailsPane">
- <title>The "Packet Details" pane</title>
- <graphic entityref="EtherealDetailsPane" format="PNG"/>
- </figure>
- </para>
- <para>
- This pane shows the protocols and protocol fields of the packet selected
- in the "Packet List" pane. The protocols and fields of the packet are
- displayed using a tree, which can be expanded and collapsed.
- </para>
- <para>
- There is a context menu (right mouse click) available, see details in
- <xref linkend="ChWorkPacketDetailsPanePopUpMenu"/>.
- </para>
- <para>
- Some protocol fields are specially displayed.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <command>Generated fields</command>
- Ethereal itself will generate additional protocol fields which are
- surrounded by brackets. The information in these fields is derived from the
- known context to other packets in the capture file. For example, Ethereal
- is doing a sequence/acknowledge analysis of each TCP stream,
- which is displayed in the [SEQ/ACK analysis] fields of the TCP protocol.
- </para>
- </listitem>
- <listitem>
- <para>
- <command>Links</command>
- If Ethereal detected a relationship to another packet in the capture file,
- it will generate a link to that packet. Links are underlined and displayed
- in blue. If double-clicked, Ethereal jumps to the corresponding packet.
- </para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section id="ChUsePacketBytesPaneSection"><title>The "Packet Bytes" pane</title>
- <para>
- The packet bytes pane shows the data of the current packet (selected in the "Packet List"
- pane) in a hexdump style.
- <figure id="ChUseEtherealBytesPane">
- <title>The "Packet Bytes" pane</title>
- <graphic entityref="EtherealBytesPane" format="PNG"/>
- </figure>
- </para>
- <para>
- As usual for a hexdump, the left side shows the offset in the packet data,
- in the middle the packet data is shown in a hexadecimal representation and
- on the right the corresponding ASCII characters (or . if not appropriate)
- are displayed.
- </para>
- <para>
- There is a context menu (right mouse click) available, see details in
- <xref linkend="ChWorkPacketBytesPanePopUpMenu"/>.
- </para>
- <para>
- Depending on the packet data, sometimes more than one page is available,
- e.g. when Ethereal has reassembled some packets into a single chunk of
- data, see <xref linkend="ChAdvReassemblySection"/>. In this case there are
- some additional tabs shown at the bottom of the pane to let you select
- the page you want to see.
- <figure id="ChUseEtherealBytesPaneTabs">
- <title>The "Packet Bytes" pane with tabs</title>
- <graphic entityref="EtherealBytesPaneTabs" format="PNG"/>
- </figure>
- </para>
- <note><title>Note!</title>
- <para>
- The additional pages might contain data picked from multiple packets.
- </para>
- </note>
- <para>
- The context menu (right mouse click) of the tab labels will show a list of
- all available pages. This can be helpful if the size in the pane is too
- small for all the tab labels.
- </para>
- </section>
-
- <section id="ChUseStatusbarSection"><title>The Statusbar</title>
- <para>
- The statusbar displays informational messages.
- </para>
- <para>
- In general, the left side will show context related information, while the
- right side will show the current number of packets.
- </para>
- <para>
- <figure id="ChUseEtherealStatusbarEmpty">
- <title>The initial Statusbar</title>
- <graphic entityref="EtherealStatusbarEmpty" format="PNG"/>
- </figure>
- This statusbar is shown while no capture file is loaded, e.g. when
- Ethereal is started.
- </para>
- <para>
- <figure id="ChUseEtherealStatusbarLoaded">
- <title>The Statusbar with a loaded capture file</title>
- <graphic entityref="EtherealStatusbarLoaded" format="PNG"/>
- </figure>
- The left side shows information about the capture file, its
- name, its size and the elapsed time while it was being captured.
- </para>
- <para>
- The right side shows the current number of packets in the
- capture file. The following values are displayed:
- <itemizedlist mark="bullet">
- <listitem>
- <para><emphasis>P:</emphasis> the number of captured packets</para>
- </listitem>
- <listitem>
- <para><emphasis>D:</emphasis> the number of packets currently being
- displayed</para>
- </listitem>
- <listitem>
- <para><emphasis>M:</emphasis> the number of marked packets</para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- <figure id="ChUseEtherealStatusbarSelected">
- <title>The Statusbar with a selected protocol field</title>
- <graphic entityref="EtherealStatusbarSelected" format="PNG"/>
- </figure>
- This is displayed if you have selected a protocol field from the
- "Packet Details" pane.
- </para>
- <tip><title>Tip!</title>
- <para>
- The value between the brackets (in this example
- <command>arp.opcode</command>) can be used as a display filter string,
- representing the selected protocol field.
- </para>
- </tip>
- </section>
-
-</chapter>
-<!-- End of EUG Chapter 3 -->
+<!-- EUG Chapter Three --> +<!-- $Id$ --> + +<chapter id="ChapterUsing"> + <title>User Interface</title> + <section id="ChUseIntroductionSection"><title>Introduction</title> + <para> + By now you have installed <application>Ethereal</application> and + are most likely keen to get started capturing your first packets. In + the next chapters we will explore: + <itemizedlist> + <listitem> + <para> + How the Ethereal user interface works + </para> + </listitem> + <listitem> + <para> + How to capture packets in <application>Ethereal</application> + </para> + </listitem> + <listitem> + <para> + How to view packets in <application>Ethereal</application> + </para> + </listitem> + <listitem> + <para> + How to filter packets in <application>Ethereal</application> + </para> + </listitem> + <listitem> + <para> + ... and many other things! + </para> + </listitem> + </itemizedlist> + </para> + </section> + + <section id="ChUseStartSection"><title>Start Ethereal</title> + <para> + You can start Ethereal from your shell or window manager. + <tip><title>Tip!</title> + <para> + When starting Ethereal it's possible to specify optional settings using + the command line. See <xref linkend="ChCustCommandLine"/> for details. + </para> + </tip> + <note><title>Note!</title> + <para> + In the following chapters, a lot of screenshots from Ethereal will be shown. + As Ethereal runs on many different platforms and there are different + versions of the underlying GUI toolkit (GTK 1.x / 2.x) used, your + screen might look different from the provided screenshots. But as there + are no real differences in functionality, these screenshots should still + be understandable. + </para> + </note> + </para> + </section> + + <section id="ChUseMainWindowSection"><title>The Main window</title> + <para> + Lets look at Ethereal's user interface. <xref linkend="ChUseFig01"/> shows + Ethereal as you would usually see it after some packets captured or loaded + (how to do this will be described later). + <figure id="ChUseFig01"> + <title>The Main window</title> + <graphic scale="100" entityref="EtherealThreePane1" format="PNG"/> + </figure> + </para> + <para> + Ethereal's main window consist of parts that are commonly known from many + other GUI programs. + <orderedlist> + <listitem> + <para> + The <emphasis>menu</emphasis> (see <xref linkend="ChUseMenuSection"/>) + is used to start actions. + </para> + </listitem> + <listitem> + <para> + The <emphasis>main toolbar</emphasis> (see <xref linkend="ChUseMainToolbarSection"/>) + provides quick access to frequently used items from the menu. + </para> + </listitem> + <listitem> + <para> + The <emphasis>filter toolbar</emphasis> (see <xref linkend="ChUseFilterToolbarSection"/>) + provides a way to directly manipulate the currently used display filter + (see <xref linkend="ChWorkDisplayFilterSection"/>). + </para> + </listitem> + <listitem> + <para> + The <emphasis>packet list pane</emphasis> (see <xref linkend="ChUsePacketListPaneSection"/>) + displays a summary of each packet captured. By clicking on packets + in this pane you control what is displayed in the other two panes. + </para> + </listitem> + <listitem> + <para> + The <emphasis>packet details pane</emphasis> (see <xref linkend="ChUsePacketDetailsPaneSection"/>) + displays the packet selected in the packet list pane in more detail. + </para> + </listitem> + <listitem> + <para> + The <emphasis>packet bytes pane</emphasis> (see <xref linkend="ChUsePacketBytesPaneSection"/>) + displays the data from the packet selected in the packet list pane, and + highlights the field selected in the packet details pane. + </para> + </listitem> + <listitem> + <para> + The <emphasis>statusbar</emphasis> (see <xref linkend="ChUseStatusbarSection"/>) + shows some detailed information about the current program state and + the captured data. + </para> + </listitem> + </orderedlist> + <tip><title>Tip!</title> + <para> + The layout of the main window can be customized by changing preference settings. + See <xref linkend="ChCustGUILayoutPrefPage"/> for details! + </para> + </tip> + </para> + </section> + + <section id="ChUseMenuSection"><title>The Menu</title> + <para> + The Ethereal menu sits on top of the Ethereal window. + An example is shown in <xref linkend="ChUseEtherealMenu"/>. + </para> + <note><title>Note!</title> + <para> + Menu items will be greyed out if the corresponding feature isn't + available. For example, you cannot save a capture file if you didn't + capture or load any data before. + </para> + </note> + <para> + <figure id="ChUseEtherealMenu"><title>The Menu</title> + <graphic entityref="EtherealMenuOnly" format="PNG"/> + </figure> + </para> + <para> + It contains the following items: + <variablelist> + <varlistentry><term><command>File</command></term> + <listitem> + <para> + This menu contains tems to open and merge capture files, + save / print / export capture files in whole or in part, + and to quit from Ethereal. See <xref linkend="ChUseFileMenuSection"/>. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Edit</command></term> + <listitem> + <para> + This menu contains items to find a packet, time reference or mark one + or more packets, set your preferences, + (cut, copy, and paste are not presently implemented). + See <xref linkend="ChUseEditMenuSection"/>. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>View</command></term> + <listitem> + <para>This menu controls the display of the captured data, + including the colorization of packets, zooming the font, + show a packet in a separate window, expand and collapse trees in packet details, .... + See <xref linkend="ChUseViewMenuSection"/>. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Go</command></term> + <listitem> + <para>This menu contains items to go to a specific packet. + See <xref linkend="ChUseGoMenuSection"/>. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Capture</command></term> + <listitem> + <para>This menu allows you to start and stop captures and to edit capture filters. + See <xref linkend="ChUseCaptureMenuSection"/>. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Analyze</command></term> + <listitem> + <para> + This menu contains items to manipulate display filters, enable or + disable the dissection of protocols, configure user specified decodes + and follow a TCP stream. + See <xref linkend="ChUseAnalyzeMenuSection"/>. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Statistics</command></term> + <listitem> + <para> + This menu contains menu-items to display various statistic windows, + including a summary of the packets that have been captured, + display protocol hierarchy statistics and much more. + See <xref linkend="ChUseStatisticsMenuSection"/>. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Help</command></term> + <listitem> + <para> + This menu contains items to help the user, like access to some basic + help, a list of the supported protocols, manual pages, online access + to some of the webpages, and the usual about dialog. + See <xref linkend="ChUseHelpMenuSection"/>. + </para> + </listitem> + </varlistentry> + </variablelist> + Each of these menu items is described in more detail in the sections + that follow. + </para> + <tip><title>Tip!</title> + <para> + You can access menu items directly or by pressing the corresponding + accelerator keys, which are shown at the right side of the + menu. For example, you can press the Control (or Strg in german) and the K + keys together to open the capture dialog. + </para> + </tip> + </section> + + <section id="ChUseFileMenuSection"><title>The "File" menu</title> + <para> + The Ethereal file menu contains the fields shown in + <xref linkend="ChUseTabFile"/>. + </para> + <figure id="ChUseEtherealFileMenu"> + <title>The "File" Menu</title> + <graphic entityref="EtherealFileMenu" format="PNG"/> + </figure> + <table id="ChUseTabFile" frame="none"><title>File menu items</title> + <tgroup cols="3"> + <colspec colnum="1" colwidth="72pt"/> + <colspec colnum="2" colwidth="80pt"/> + <thead> + <row> + <entry>Menu Item</entry> + <entry>Accelerator</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><command>Open...</command></entry> + <entry>Ctrl+O</entry> + <entry><para> + This menu item brings up the file open dialog box that + allows you to load a capture file for viewing. It is + discussed in more detail in <xref linkend="ChIOOpen"/>. + </para></entry> + </row> + <row> + <entry><command>Open Recent</command></entry> + <entry></entry> + <entry><para> + This menu item shows a submenu containing the recently opened + capture files. Clicking on one of the submenu items will open the + corresponding capture file directly. + </para></entry> + </row> + <row> + <entry><command>Merge...</command></entry> + <entry></entry> + <entry><para> + This menu item brings up the merge file dialog box that + allows you to merge a capture file into the currently loaded one. + It is discussed in more detail in <xref linkend="ChIOMergeSection"/>. + </para></entry> + </row> + <row> + <entry><command>Close</command></entry> + <entry>Ctrl+W</entry> + <entry><para> + This menu item closes the current capture. If you + haven't saved the capture, you will be asked to do so first + (this can be disabled by a preference setting). + </para></entry> + </row> + <row> + <entry><command>------</command></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><command>Save</command></entry> + <entry>Ctrl+S</entry> + <entry><para> + This menu item saves the current capture. If you + have not set a default capture file name (perhaps with + the -w <capfile> option), Ethereal pops up the + Save Capture File As dialog box (which is discussed + further in <xref linkend="ChIOSaveAs"/>). + </para><note> + <title>Note!</title> + <para> + If you have already saved the current capture, this + menu item will be greyed out. + </para> + </note><note> + <title>Note!</title> + <para> + You cannot save a live capture while it is in + progress. You must stop the capture in order to + save. + </para> + </note></entry> + </row> + <row> + <entry><command>Save As...</command></entry> + <entry>Shift+Ctrl+S</entry> + <entry><para> + This menu item allows you to save the current capture + file to whatever file you would like. It pops up the + Save Capture File As dialog box (which is discussed + further in <xref linkend="ChIOSaveAs"/>). + </para></entry> + </row> + <row> + <entry><command>------</command></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><command>Export > as "Plain Text" file...</command></entry> + <entry></entry> + <entry><para> + This menu item allows you to export all, or some, of the packets in + the capture file to a plain ASCII text file. + It pops up the Ethereal Export dialog box (which is discussed further in + <xref linkend="ChIOExportPlainDialog"/>). + </para></entry> + </row> + <row> + <entry><command>Export > as "PostScript" file...</command></entry> + <entry></entry> + <entry><para> + This menu item allows you to export the (or some) of the packets in + the capture file to a PostScript file. + It pops up the Ethereal Export dialog box (which is discussed further in + <xref linkend="ChIOExportPSDialog"/>). + </para></entry> + </row> + <row> + <entry><command>Export > as "PSML" file...</command></entry> + <entry></entry> + <entry><para> + This menu item allows you to export the (or some) of the packets in + the capture file to a PSML (packet summary markup language) XML file. + It pops up the Ethereal Export dialog box (which is discussed further in + <xref linkend="ChIOExportPSMLDialog"/>). + </para></entry> + </row> + <row> + <entry><command>Export > as "PDML" file...</command></entry> + <entry></entry> + <entry><para> + This menu item allows you to export the (or some) of the packets in + the capture file to a PDML (packet details markup language) XML file. + It pops up the Ethereal Export dialog box (which is discussed further in + <xref linkend="ChIOExportPDMLDialog"/>). + </para></entry> + </row> + <row> + <entry><command>Export > Selected Packet Bytes...</command></entry> + <entry>Ctrl+H</entry> + <entry><para> + This menu item allows you to export the currently selected bytes + in the packet bytes pane to a binary file. It pops up the + Ethereal Export dialog box (which is discussed further in + <xref linkend="ChIOExportSelectedDialog"/>) + </para></entry> + </row> + <row> + <entry><command>------</command></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><command>Print...</command></entry> + <entry>Ctrl+P</entry> + <entry><para> + This menu item allows you to print all (or some of) the packets in + the capture file. It pops up the Ethereal Print dialog + box (which is discussed further in + <xref linkend="ChIOPrintSection"/>). + </para></entry> + </row> + <row> + <entry><command>------</command></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><command>Quit</command></entry> + <entry>Ctrl+Q</entry> + <entry><para> + This menu item allows you to quit from Ethereal. + Ethereal will ask to save your capture file if you haven't saved + it before (this can be disabled by a preference setting). + </para></entry> + </row> + </tbody> + </tgroup> + </table> + </section> + + <section id="ChUseEditMenuSection"><title>The "Edit" menu</title> + <para> + The Ethereal Edit menu contains the fields shown in + <xref linkend="ChUseTabEdit"/>. + </para> + <figure id="ChUseEtherealEditMenu"> + <title>The "Edit" Menu</title> + <graphic entityref="EtherealEditMenu" format="PNG"/> + </figure> + <table id="ChUseTabEdit" frame="none"> + <title>Edit menu items</title> + <tgroup cols="3"> + <colspec colnum="1" colwidth="72pt"/> + <colspec colnum="2" colwidth="80pt"/> + <thead> + <row> + <entry>Menu Item</entry> + <entry>Accelerator</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><command>Find Packet...</command></entry> + <entry>Ctrl+F</entry> + <entry><para> + This menu item brings up a dialog box that allows you + to find a packet by many criteria. + There is further information on finding packets in + <xref linkend="ChWorkFindPacketSection"/>. + </para></entry> + </row> + <row> + <entry><command>Find Next</command></entry> + <entry>Ctrl+N</entry> + <entry><para> + This menu item tries to find the next packet matching the + settings from "Find Packet...". + </para></entry> + </row> + <row> + <entry><command>Find Previous</command></entry> + <entry>Ctrl+B</entry> + <entry><para> + This menu item tries to find the previous packet matching the + settings from "Find Packet...". + </para></entry> + </row> + <row> + <entry><command>------</command></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><command>Time Reference > Set Time Reference</command></entry> + <entry>Ctrl+T</entry> + <entry><para> + This menu item set a time reference on the currently selected + packet. See <xref linkend="ChWorkTimeReferencePacketSection"/> for more information + about the time referenced packets. + </para></entry> + </row> + <row> + <entry><command>Time Reference > Find Next</command></entry> + <entry></entry> + <entry><para> + This menu item tries to find the next time referenced packet. + </para></entry> + </row> + <row> + <entry><command>Time Reference > Find Previous</command></entry> + <entry></entry> + <entry><para> + This menu item tries to find the previous time referenced packet. + </para></entry> + </row> + <row> + <entry><command>Mark Packet</command></entry> + <entry>Ctrl+M</entry> + <entry><para> + This menu item "marks" the currently selected packet. See + <xref linkend="ChWorkMarkPacketSection"/> for details. + </para></entry> + </row> + <row> + <entry><command>Mark All Packets</command></entry> + <entry></entry> + <entry><para> + This menu item "marks" all packets. + </para></entry> + </row> + <row> + <entry><command>Unmark All Packets</command></entry> + <entry></entry> + <entry><para>This menu item "unmarks" all marked packets. + </para></entry> + </row> + <row> + <entry><command>------</command></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><command>Preferences...</command></entry> + <entry>Shift+Ctrl+P</entry> + <entry><para> + This menu item brings up a dialog box that allows + you to set preferences for many parameters that control + Ethereal. You can also save your preferences so Ethereal + will use them the next time you start it. More detail + is provided in <xref linkend="ChCustPreferencesSection"/>. + </para></entry> + </row> + </tbody> + </tgroup> + </table> + </section> + + <section id="ChUseViewMenuSection"><title>The "View" menu</title> + <para> + The Ethereal View menu contains the fields shown in + <xref linkend="ChUseTabView"/>. + </para> + <figure id="ChUseEtherealViewMenu"> + <title>The "View" Menu</title> + <graphic entityref="EtherealViewMenu" format="PNG"/> + </figure> + <table id="ChUseTabView" frame="none"> + <title>View menu items</title> + <tgroup cols="3"> + <colspec colnum="1" colwidth="72pt"/> + <colspec colnum="2" colwidth="80pt"/> + <thead> + <row> + <entry>Menu Item</entry> + <entry>Accelerator</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><command>Main Toolbar</command></entry> + <entry></entry> + <entry><para> + This menu item hides or shows the main toolbar, see + <xref linkend="ChUseMainToolbarSection"/>. + </para></entry> + </row> + <row> + <entry><command>Filter Toolbar</command></entry> + <entry></entry> + <entry><para> + This menu item hides or shows the filter toolbar, see + <xref linkend="ChUseFilterToolbarSection"/>. + </para></entry> + </row> + <row> + <entry><command>Statusbar</command></entry> + <entry></entry> + <entry><para> + This menu item hides or shows the statusbar, see + <xref linkend="ChUseStatusbarSection"/>. + </para></entry> + </row> + <row> + <entry><command>------</command></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><command>Packet List</command></entry> + <entry></entry> + <entry><para> + This menu item hides or shows the packet list pane, see + <xref linkend="ChUsePacketListPaneSection"/>. + </para></entry> + </row> + <row> + <entry><command>Packet Details</command></entry> + <entry></entry> + <entry><para> + This menu item hides or shows the packet details pane, see + <xref linkend="ChUsePacketDetailsPaneSection"/>. + </para></entry> + </row> + <row> + <entry><command>Packet Bytes</command></entry> + <entry></entry> + <entry><para> + This menu item hides or shows the packet bytes pane, see + <xref linkend="ChUsePacketBytesPaneSection"/>. + </para></entry> + </row> + <row> + <entry><command>------</command></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><command>Time Display Format > Time of Day</command></entry> + <entry></entry> + <entry><para> + Selecting this tells Ethereal to display time + stamps in time of day format, see + <xref linkend="ChWorkTimeFormatsSection"/>. + <note><title>Note!</title> + <para> + The fields "Time of Day", "Date and Time of + Day", "Seconds Since Beginning of Capture" and "Seconds Since + Previous Packet" are mutually exclusive. + </para> + </note> + </para></entry> + </row> + <row> + <entry><command>Time Display Format > Date and Time of Day</command></entry> + <entry></entry> + <entry><para> + Selecting this tells Ethereal to display the + time stamps in date and time of day format, see + <xref linkend="ChWorkTimeFormatsSection"/>. + </para></entry> + </row> + <row> + <entry><command>Time Display Format > Seconds Since Beginning of Capture</command></entry> + <entry></entry> + <entry><para> + Selecting this tells Ethereal to display time + stamps in seconds since beginning of capture format, see + <xref linkend="ChWorkTimeFormatsSection"/>. + </para></entry> + </row> + <row> + <entry><command>Time Display Format > Seconds Since Previous Packet</command></entry> + <entry></entry> + <entry><para> + Selecting this tells Ethereal to display time stamps in + seconds since previous packet format, see + <xref linkend="ChWorkTimeFormatsSection"/>. + </para></entry> + </row> + <row> + <entry><command>Name Resolution > Resolve Name</command></entry> + <entry></entry> + <entry><para> + This item allows you to trigger a name resolve of the current packet + only, see <xref linkend="ChAdvNameResolutionSection"/>. + </para></entry> + </row> + <row> + <entry><command>Name Resolution > Enable for MAC Layer</command></entry> + <entry></entry> + <entry><para> + This item allows you to control whether or not + Ethereal translates MAC addresses into names, see + <xref linkend="ChAdvNameResolutionSection"/>. + </para></entry> + </row> + <row> + <entry><command>Name Resolution > Enable for Network Layer</command></entry> + <entry></entry> + <entry><para> + This item allows you to control whether or not + Ethereal translates network addresses into names, see + <xref linkend="ChAdvNameResolutionSection"/>. + </para></entry> + </row> + <row> + <entry><command>Name Resolution > Enable for Transport Layer</command></entry> + <entry></entry> + <entry><para> + This item allows you to control whether or not + Ethereal translates transport addresses into names, see + <xref linkend="ChAdvNameResolutionSection"/>. + </para></entry> + </row> + <row> + <entry><command>Auto Scroll in Live Capture</command></entry> + <entry></entry> + <entry><para> + This item allows you to specify that Ethereal + should scroll the packet list pane as new packets come + in, so you are always looking at the last packet. If you + do not specify this, Ethereal simply adds new packets onto + the end of the list, but does not scroll the packet list + pane. + </para></entry> + </row> + <row> + <entry><command>------</command></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><command>Zoom In</command></entry> + <entry>Ctrl++</entry> + <entry><para> + Zoom into the packet data (increase the font size). + </para></entry> + </row> + <row> + <entry><command>Zoom Out</command></entry> + <entry>Ctrl+-</entry> + <entry><para> + Zoom out of the packet data (decrease the font size). + </para></entry> + </row> + <row> + <entry><command>Normal Size</command></entry> + <entry>Ctrl+=</entry> + <entry><para> + Set zoom level back to 100% (set font size back to normal). + </para></entry> + </row> + <row> + <entry><command>------</command></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><command>Collapse All</command></entry> + <entry></entry> + <entry><para> + Ethereal keeps a list of all the protocol subtrees + that are expanded, and uses it to ensure that the + correct subtrees are expanded when you display a packet. + This menu item collapses the tree view of all packets + in the capture list. + </para></entry> + </row> + <row> + <entry><command>Expand All</command></entry> + <entry></entry> + <entry><para> + This menu item expands all subtrees in all packets in + the capture. + </para></entry> + </row> + <row> + <entry><command>Expand Tree</command></entry> + <entry></entry> + <entry><para> + This menu item expands the currently selected subtree in the + packet details tree. + </para></entry> + </row> + <row> + <entry><command>------</command></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><command>Coloring Rules...</command></entry> + <entry></entry> + <entry><para> + This menu item brings up a dialog box that allows you + to color packets in the packet list pane according to + filter expressions you choose. It can be very useful + for spotting certain types of packets, see + <xref linkend="ChCustColorizationSection"/>. + </para></entry> + </row> + <row> + <entry><command>------</command></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><command>Show Packet in New Window</command></entry> + <entry></entry> + <entry><para> + This menu item brings up the selected packet in a + separate window. The separate window shows only the + tree view and byte view panes. + </para></entry> + </row> + <row> + <entry><command>Reload</command></entry> + <entry>Ctrl-R</entry> + <entry><para> + This menu item allows you to reload the current + capture file. + </para></entry> + </row> + </tbody> + </tgroup> + </table> + </section> + + <section id="ChUseGoMenuSection"><title>The "Go" menu</title> + <para> + The Ethereal Go menu contains the fields shown in + <xref linkend="ChUseTabGo"/>. + </para> + <figure id="ChUseEtherealGoMenu"> + <title>The "Go" Menu</title> + <graphic entityref="EtherealGoMenu" format="PNG"/> + </figure> + <table id="ChUseTabGo" frame="none"> + <title>Go menu items</title> + <tgroup cols="3"> + <colspec colnum="1" colwidth="72pt"/> + <colspec colnum="2" colwidth="80pt"/> + <thead> + <row> + <entry>Menu Item</entry> + <entry>Accelerator</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><command>Go to Packet...</command></entry> + <entry>Ctrl-G</entry> + <entry><para> + This menu item brings up a dialog box that allows you + to specify a packet number, and then goes to that packet. See + <xref linkend="ChWorkGoToPacketSection"/> for details. + </para></entry> + </row> + <row> + <entry><command>Go to Corresponding Packet</command></entry> + <entry></entry> + <entry><para> + This menu item goes to the corresponding packet of the currently + selected protocol field. If the selected field doesn't correspond + to a packet, this item is greyed out. + </para></entry> + </row> + <row> + <entry><command>------</command></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><command>First Packet</command></entry> + <entry></entry> + <entry><para> + This menu item jumps to the first packet of the capture file. + </para></entry> + </row> + <row> + <entry><command>Last Packet</command></entry> + <entry></entry> + <entry><para> + This menu item jumps to the last packet of the capture file. + </para></entry> + </row> + </tbody> + </tgroup> + </table> + </section> + + <section id="ChUseCaptureMenuSection"><title>The "Capture" menu</title> + <para> + The Ethereal Capture menu contains the fields shown in + <xref linkend="ChUseTabCap"/>. + </para> + <figure id="ChUseEtherealCaptureMenu"> + <title>The "Capture" Menu</title> + <graphic entityref="EtherealCaptureMenu" format="PNG"/> + </figure> + <table id="ChUseTabCap" frame="none"> + <title>Capture menu items</title> + <tgroup cols="3"> + <colspec colnum="1" colwidth="72pt"/> + <colspec colnum="2" colwidth="80pt"/> + <thead> + <row> + <entry>Menu Item</entry> + <entry>Accelerator</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><command>Start...</command></entry> + <entry>Ctrl+K</entry> + <entry><para> + This menu item brings up the Capture Options + dialog box (discussed further in + <xref linkend="ChCapCaptureOptions"/>) and allows you to + start capturing packets. + </para></entry> + </row> + <row> + <entry><command>Stop</command></entry> + <entry>Ctrl+E</entry> + <entry><para> + This menu item stops the currently running capture, see + <xref linkend="ChCapStopSection"/>) . + </para></entry> + </row> + <row> + <entry><command>Capture Filters...</command></entry> + <entry></entry> + <entry><para> + This menu item brings up a dialog box that allows you to + create and edit capture filters. You can name filters, + and you can save them for future use. More detail on + this subject is provided in + <xref linkend="ChWorkDefineFilterSection"/> + </para></entry> + </row> + </tbody> + </tgroup> + </table> + </section> + + <section id="ChUseAnalyzeMenuSection"><title>The "Analyze" menu</title> + <para> + The Ethereal Analyze menu contains the fields shown in + <xref linkend="ChUseAnalyze"/>. + </para> + <figure id="ChUseEtherealAnalyzeMenu"> + <title>The "Analyze" Menu</title> + <graphic entityref="EtherealAnalyzeMenu" format="PNG"/> + </figure> + <table id="ChUseAnalyze" frame="none"><title>Analyze menu items</title> + <tgroup cols="3"> + <colspec colnum="1" colwidth="72pt"/> + <colspec colnum="2" colwidth="80pt"/> + <thead> + <row> + <entry>Menu Item</entry> + <entry>Accelerator</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><command>Display Filters...</command></entry> + <entry></entry> + <entry><para> + This menu item brings up a dialog box that allows you + to create and edit display filters. You can name + filters, and you can save them for future use. More + detail on this subject is provided in + <xref linkend="ChWorkDefineFilterSection"/> + </para></entry> + </row> + <row> + <entry><command>Apply as Filter > ...</command></entry> + <entry></entry> + <entry><para> + These menu items will change the current display filter and apply + the changed filter immediately. Depending on the chosen menu item, + the current display filter string will be replaced or appended to + by the selected protocol field in the packet details pane. + </para></entry> + </row> + <row> + <entry><command>Prepare a Filter > ...</command></entry> + <entry></entry> + <entry><para> + These menu items will change the current display filter but won't + apply the changed filter. Depending on the chosen menu item, + the current display filter string will be replaced or appended to + by the selected protocol field in the packet details pane. + </para></entry> + </row> + <row> + <entry><command>------</command></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><command>Enabled Protocols...</command></entry> + <entry>Shift+Ctrl+R</entry> + <entry><para> + This menu item allows the user to enable/disable protocol + dissectors, see <xref linkend="ChAdvEnabledProtocols"/> + </para></entry> + </row> + <row> + <entry><command>Decode As...</command></entry> + <entry></entry> + <entry><para> + This menu item allows the user to force Ethereal to + decode certain packets as a particular protocol, see + <xref linkend="ChAdvDecodeAs"/> + </para></entry> + </row> + <row> + <entry><command>User Specified Decodes...</command></entry> + <entry></entry> + <entry><para> + This menu item allows the user to force Ethereal to + decode certain packets as a particular protocol, see + <xref linkend="ChAdvDecodeAsShow"/> + </para></entry> + </row> + <row> + <entry><command>------</command></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><command>Follow TCP Stream</command></entry> + <entry></entry> + <entry><para> + This menu item brings up a separate window and displays + all the TCP segments captured that are on the same TCP + connection as a selected packet, see + <xref linkend="ChAdvFollowTCPSection"/> + </para></entry> + </row> + </tbody> + </tgroup> + </table> + </section> + + <section id="ChUseStatisticsMenuSection"><title>The "Statistics" menu</title> + <para> + The Ethereal Statistics menu contains the fields shown in + <xref linkend="ChUseStatistics"/>. + </para> + <figure id="ChUseEtherealStatisticsMenu"> + <title>The "Statistics" Menu</title> + <graphic entityref="EtherealStatisticsMenu" format="PNG"/> + </figure> + <para> + All menu items will bring up a new window showing specific statistical + information. + </para> + <table id="ChUseStatistics" frame="none"> + <title>Statistics menu items</title> + <tgroup cols="3"> + <colspec colnum="1" colwidth="72pt"/> + <colspec colnum="2" colwidth="80pt"/> + <thead> + <row> + <entry>Menu Item</entry> + <entry>Accelerator</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><command>Summary</command></entry> + <entry></entry> + <entry><para> + Show information about the data captured, see <xref + linkend="ChStatSummary"/>. + </para></entry> + </row> + <row> + <entry><command>Protocol Hierarchy</command></entry> + <entry></entry> + <entry><para> + Display a hierarchical tree of protocol statistics, see <xref + linkend="ChStatHierarchy"/>. + </para></entry> + </row> + <row> + <entry><command>Conversations</command></entry> + <entry></entry> + <entry><para> + Display a list of conversations (traffic between two endpoints), + see <xref linkend="ChStatConversationsWindow"/>. + </para></entry> + </row> + <row> + <entry><command>Endpoints</command></entry> + <entry></entry> + <entry><para> + Display a list of endpoints (traffic to/from an address), see + <xref linkend="ChStatEndpointsWindow"/>. + </para></entry> + </row> + <row> + <entry><command>IO Graphs</command></entry> + <entry></entry> + <entry><para> + Display user specified graphs (e.g. the number of packets in the + course of time), see <xref linkend="ChStatIOGraphs"/>. + </para></entry> + </row> + <row> + <entry><command>------</command></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><command>Conversation List</command></entry> + <entry></entry> + <entry><para> + Display a list of conversations, obsoleted by the combined window + of Conversations above, see + <xref linkend="ChStatConversationListWindow"/>. + </para></entry> + </row> + <row> + <entry><command>Endpoint List</command></entry> + <entry></entry> + <entry><para> + Display a list of endpoints, obsoleted by the combined window + of Endpoints above, see + <xref linkend="ChStatEndpointListWindow"/>. + </para></entry> + </row> + <row> + <entry><command>Service Response Time</command></entry> + <entry></entry> + <entry><para> + Display the time between a request and the corresponding response, see + <xref linkend="ChStatSRT"/>. + </para></entry> + </row> + <row> + <entry><command>------</command></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><command>ANSI</command></entry> + <entry></entry> + <entry><para>See <xref linkend="ChStatXXX"/></para></entry> + </row> + <row> + <entry><command>BOOTP-DHCP</command></entry> + <entry></entry> + <entry><para>See <xref linkend="ChStatXXX"/></para></entry> + </row> + <row> + <entry><command>GSM</command></entry> + <entry></entry> + <entry><para>See <xref linkend="ChStatXXX"/></para></entry> + </row> + <row> + <entry><command>HTTP</command></entry> + <entry></entry> + <entry><para>HTTP request/response statistics, see <xref linkend="ChStatXXX"/></para></entry> + </row> + <row> + <entry><command>ISUP Message Types</command></entry> + <entry></entry> + <entry><para>See <xref linkend="ChStatXXX"/></para></entry> + </row> + <row> + <entry><command>ITU-T H.225</command></entry> + <entry></entry> + <entry><para>See <xref linkend="ChStatXXX"/></para></entry> + </row> + <row> + <entry><command>MTP3</command></entry> + <entry></entry> + <entry><para>See <xref linkend="ChStatXXX"/></para></entry> + </row> + <row> + <entry><command>ONC-RPC Programs</command></entry> + <entry></entry> + <entry><para>See <xref linkend="ChStatXXX"/></para></entry> + </row> + <row> + <entry><command>RTP</command></entry> + <entry></entry> + <entry><para>See <xref linkend="ChStatXXX"/></para></entry> + </row> + <row> + <entry><command>SIP</command></entry> + <entry></entry> + <entry><para>See <xref linkend="ChStatXXX"/></para></entry> + </row> + <row> + <entry><command>TCP Stream Graph</command></entry> + <entry></entry> + <entry><para>See <xref linkend="ChStatXXX"/></para></entry> + </row> + <row> + <entry><command>WAP-WSP</command></entry> + <entry></entry> + <entry><para>See <xref linkend="ChStatXXX"/></para></entry> + </row> + </tbody> + </tgroup> + </table> + </section> + + <section id="ChUseHelpMenuSection"><title>The "Help" menu</title> + <para> + The Ethereal Help menu contains the fields shown in + <xref linkend="ChUseHelp"/>. + </para> + <figure id="ChUseEtherealHelpMenu"> + <title>The "Help" Menu</title> + <graphic entityref="EtherealHelpMenu" format="PNG"/> + </figure> + <table id="ChUseHelp" frame="none"> + <title>Help menu items</title> + <tgroup cols="3"> + <colspec colnum="1" colwidth="72pt"/> + <colspec colnum="2" colwidth="80pt"/> + <thead> + <row> + <entry>Menu Item</entry> + <entry>Accelerator</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><command>Contents</command></entry> + <entry>F1</entry> + <entry><para> + This menu item brings up a basic help system. + </para></entry> + </row> + <row> + <entry><command>Supported Protocols</command></entry> + <entry></entry> + <entry><para> + This menu item brings up a dialog box showing the supported + protocols and protocol fields. + </para></entry> + </row> + <row> + <entry><command>Manual Pages > ...</command></entry> + <entry></entry> + <entry><para> + This menu item starts a Web browser showing one of the locally + installed html manual pages. + </para></entry> + </row> + <row> + <entry><command>Ethereal Online > ...</command></entry> + <entry></entry> + <entry><para> + This menu item tries to start a Web browser showing a specific + webpage from: + <ulink url="&EtherealWebSite;">&EtherealWebSite;</ulink>. + </para></entry> + </row> + <row> + <entry><command>------</command></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><command>About Ethereal</command></entry> + <entry></entry> + <entry><para> + This menu item brings up an information window that + provides some information on Ethereal, such as the plugins, the + used folders, ... + </para></entry> + </row> + </tbody> + </tgroup> + </table> + </section> + + <section id="ChUseMainToolbarSection"><title>The "Main" toolbar</title> + <para> + The main toolbar provides quick access to frequently used items from the + menu. This toolbar cannot be customized by the user, but it can be hidden + using the View menu, if the space on the screen is needed to show even + more packet data. + </para> + <para> + As in the menu, only the items useful in the current program state will + be available. The others will be greyed out (e.g. you cannot save a capture + file if you haven't loaded one). + <figure id="ChUseEtherealMainToolbar"> + <title>The "Main" toolbar</title> + <graphic entityref="EtherealMainToolbar" format="PNG"/> + </figure> + </para> + <table id="ChUseMainToolbar" frame="none"> + <title>Main toolbar items</title> + <tgroup cols="4"> + <colspec colnum="1" colwidth="40pt"/> + <colspec colnum="2" colwidth="80pt"/> + <colspec colnum="3" colwidth="80pt"/> + <thead> + <row> + <entry>Toolbar Icon</entry> + <entry>Toolbar Item</entry> + <entry>Corresponding Menu Item</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><graphic entityref="EtherealToolbarCapture" format="PNG"/></entry> + <entry><command>Start Capture...</command></entry> + <entry>Capture/Start...</entry> + <entry><para> + This item brings up the Capture Options + dialog box (discussed further in + <xref linkend="ChCapCapturingSection"/>) and allows you to + start capturing packets. + </para> + <note><title>Note!</title> + <para> + If a live capture is in progress, and you are using "Update List + of Packets in Realtime", this icon will be replaced by the Stop + Capture icon + <inlinegraphic entityref="EtherealToolbarStop" format="PNG"/>. + </para></note> + </entry> + </row> + <row> + <entry><graphic entityref="EtherealToolbarStop" format="PNG"/></entry> + <entry><command>Stop Capture</command></entry> + <entry>Capture/Stop</entry> + <entry><para> + This item stops the currently running live capture process + <xref linkend="ChCapCapturingSection"/>). + </para> + <note><title>Note!</title> + <para> + This icon is shown if a live capture is in progress, and you are + using "Update List of Packets in Realtime", otherwise the Start + Capture icon + <inlinegraphic entityref="EtherealToolbarCapture" format="PNG"/> + is shown. + </para></note> + </entry> + </row> + <row> + <entry><command>------</command></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><graphic entityref="EtherealToolbarOpen" format="PNG"/></entry> + <entry><command>Open...</command></entry> + <entry>File/Open...</entry> + <entry><para> + This item brings up the file open dialog box that + allows you to load a capture file for viewing. It is + discussed in more detail in <xref linkend="ChIOOpen"/>. + </para></entry> + </row> + <row> + <entry><graphic entityref="EtherealToolbarSaveAs" format="PNG"/></entry> + <entry><command>Save As...</command></entry> + <entry>File/Save As...</entry> + <entry><para> + This item allows you to save the current capture file to whatever + file you would like. It pops up the Save Capture File As dialog + box (which is discussed further in <xref linkend="ChIOSaveAs"/>). + </para> + <note><title>Note!</title> + <para> + If you currently have a temporary capture file, the Save icon + <inlinegraphic entityref="EtherealToolbarSave" format="PNG"/> will be + shown instead. + </para></note> + </entry> + </row> + <row> + <entry><graphic entityref="EtherealToolbarClose" format="PNG"/></entry> + <entry><command>Close</command></entry> + <entry>File/Close</entry> + <entry><para> + This item closes the current capture. If you + have not saved the capture, you will be asked to save it first. + </para></entry> + </row> + <row> + <entry><graphic entityref="EtherealToolbarReload" format="PNG"/></entry> + <entry><command>Reload</command></entry> + <entry>View/Reload</entry> + <entry><para> + This item allows you to reload the current capture file. + </para></entry> + </row> + <row> + <entry><graphic entityref="EtherealToolbarPrint" format="PNG"/></entry> + <entry><command>Print...</command></entry> + <entry>File/Print...</entry> + <entry><para> + This item allows you to print all (or some of) the packets in + the capture file. It pops up the Ethereal Print dialog + box (which is discussed further in + <xref linkend="ChIOPrintSection"/>). + </para></entry> + </row> + <row> + <entry><command>------</command></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><graphic entityref="EtherealToolbarFind" format="PNG"/></entry> + <entry><command>Find Packet...</command></entry> + <entry>Edit/Find Packet...</entry> + <entry><para> + This item brings up a dialog box that allows you + to find a packet. There is further information on finding packets + in <xref linkend="ChWorkFindPacketSection"/>. + </para></entry> + </row> + <row> + <entry><graphic entityref="EtherealToolbarFindPrevious" format="PNG"/></entry> + <entry><command>Find Previous</command></entry> + <entry>Edit/Find Previous</entry> + <entry><para> + This item tries to find the previous packet, matching the + settings from "Find Packet...". + </para></entry> + </row> + <row> + <entry><graphic entityref="EtherealToolbarFindNext" format="PNG"/></entry> + <entry><command>Find Next</command></entry> + <entry>Edit/Find Next</entry> + <entry><para> + This item tries to find the next packet, matching the + settings from "Find Packet...". + </para></entry> + </row> + <row> + <entry><command>------</command></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><graphic entityref="EtherealToolbarGoTo" format="PNG"/></entry> + <entry><command>Go to Packet...</command></entry> + <entry>Go/Go to Packet...</entry> + <entry><para> + This item brings up a dialog box that allows you + to specify a packet number to go to that packet. + </para></entry> + </row> + <row> + <entry><graphic entityref="EtherealToolbarGoFirst" format="PNG"/></entry> + <entry><command>Go To First Packet</command></entry> + <entry>Go/First Packet</entry> + <entry><para> + This item jumps to the first packet of the capture file. + </para></entry> + </row> + <row> + <entry><graphic entityref="EtherealToolbarGoLast" format="PNG"/></entry> + <entry><command>Go To Last Packet</command></entry> + <entry>Go/Last Packet</entry> + <entry><para> + This item jumps to the last packet of the capture file. + </para></entry> + </row> + <row> + <entry><command>------</command></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><graphic entityref="EtherealToolbarZoomIn" format="PNG"/></entry> + <entry><command>Zoom In</command></entry> + <entry>View/Zoom In</entry> + <entry><para> + Zoom into the packet data (increase the font size). + </para></entry> + </row> + <row> + <entry><graphic entityref="EtherealToolbarZoomOut" format="PNG"/></entry> + <entry><command>Zoom Out</command></entry> + <entry>View/Zoom Out</entry> + <entry><para> + Zoom out of the packet data (decrease the font size). + </para></entry> + </row> + <row> + <entry><graphic entityref="EtherealToolbarZoom100" format="PNG"/></entry> + <entry><command>Normal Size</command></entry> + <entry>View/Normal Size</entry> + <entry><para> + Set zoom level back to 100%. + </para></entry> + </row> + <row> + <entry><command>------</command></entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry><graphic entityref="EtherealToolbarCaptureFilters" format="PNG"/></entry> + <entry><command>Capture Filters...</command></entry> + <entry>Capture/Capture Filters...</entry> + <entry><para> + This item brings up a dialog box that allows you to + create and edit capture filters. You can name filters, + and you can save them for future use. More detail on + this subject is provided in + <xref linkend="ChWorkDefineFilterSection"/>. + </para></entry> + </row> + <row> + <entry><graphic entityref="EtherealToolbarDisplayFilters" format="PNG"/></entry> + <entry><command>Display Filters...</command></entry> + <entry>Analyze/Display Filters...</entry> + <entry><para> + This item brings up a dialog box that allows you + to create and edit display filters. You can name + filters, and you can save them for future use. More + detail on this subject is provided in + <xref linkend="ChWorkDefineFilterSection"/>. + </para></entry> + </row> + <row> + <entry><graphic entityref="EtherealToolbarColoringRules" format="PNG"/></entry> + <entry><command>Coloring Rules...</command></entry> + <entry>View/Coloring Rules...</entry> + <entry><para> + This item brings up a dialog box that allows you + color packets in the packet list pane according to + filter expressions you choose. It can be very useful + for spotting certain types of packets. More + detail on this subject is provided in + <xref linkend="ChCustColorizationSection"/>. + </para></entry> + </row> + <row> + <entry><graphic entityref="EtherealToolbarPreferences" format="PNG"/></entry> + <entry><command>Preferences...</command></entry> + <entry>Edit/Preferences</entry> + <entry><para> + This item brings up a dialog box that allows + you to set preferences for many parameters that control + Ethereal. You can also save your preferences so Ethereal + will use them the next time you start it. More detail + is provided in <xref linkend="ChCustPreferencesSection"/> + </para></entry> + </row> + </tbody> + </tgroup> + </table> + </section> + + <section id="ChUseFilterToolbarSection"><title>The "Filter" toolbar</title> + <para> + The filter toolbar lets you quickly edit and apply display filters. More information on + display filters is available in <xref linkend="ChWorkDisplayFilterSection"/>. + <figure id="ChUseEtherealFilterToolbar"> + <title>The "Filter" toolbar</title> + <graphic entityref="EtherealFilterToolbar" format="PNG"/> + </figure> + <itemizedlist> + <listitem> + <para> + The leftmost button labeled "Filter:" can be clicked to + bring up the filter construction dialog, described in <xref linkend="FiltersDialog"/>. + </para> + </listitem> + <listitem> + <para> + The left middle text box provides an area to enter or edit display + filter strings, see <xref linkend="ChWorkBuildDisplayFilterSection"/> + . A syntax check of your filter string is done while you are typing. + The background will turn red if you enter an incomplete or invalid + string, and will become green when you enter a valid string. You can + click on the pull down arrow to select a previously-entered filter + string from a list. The entries in the pull down list will remain + available even after a program restart. + </para> + <note><title>Note!</title> + <para> + After you've changed something in this field, don't forget to press + the Apply button (or the Enter/Return key), to apply this filter + string to the display. + </para> + </note> + <note><title>Note!</title> + <para> + This field is also where the current filter in effect is displayed. + </para> + </note> + </listitem> + <listitem> + <para> + The middle button labeled "Add Expression..." opens a dialog box that lets + you edit a display filter from a list of protocol fields, described in + <xref linkend="ChWorkFilterAddExpressionSection"/> + </para> + </listitem> + <listitem> + <para> + The right middle button labeled "Clear" resets the current + display filter and clears the edit area. + </para> + </listitem> + <listitem> + <para> + The rightmost button labeled "Apply" applies the current + value in the edit area as the new display filter. + </para> + </listitem> + </itemizedlist> + </para> + <note><title>Note!</title> + <para> + Applying a display filter on large capture files might take quite a long time! + </para> + </note> + </section> + + <section id="ChUsePacketListPaneSection"><title>The "Packet List" pane</title> + <para> + The packet list pane displays all the packets in the current capture + file. + <figure id="ChUseEtherealListPane"> + <title>The "Packet List" pane</title> + <graphic entityref="EtherealListPane" format="PNG"/> + </figure> + Each line in the packet list corrresponds to one packet in the capture + file. If you select a line in this pane, more details will be displayed in + the "Packet Details" and "Packet Bytes" panes. + </para> + <para> + While dissecting a packet, Ethereal will place information from the + protocol dissectors into the columns. As higher level protocols might + overwrite information from lower levels, you will typically see the + information from the highest possible level only. + </para> + <para> + For example, let's look at a packet containing TCP inside IP inside + an Ethernet packet. The Ethernet dissector will write its data (such as + the Ethernet addresses), the IP dissector will overwrite this by its own + (such as the IP addresses), the TCP dissector will overwrite the IP + information, and so on. + </para> + <para> + There are a lot of different columns available. Which columns are + displayed can be selected by preference settings, see + <xref linkend="ChCustGUIColumnsPrefPage"/>. + </para> + <para> + The default columns will show: + <itemizedlist> + <listitem> + <para><command>No.</command> + The number of the packet in the capture file. This number won't change, + even if a display filter is used. + </para> + </listitem> + <listitem> + <para><command>Time</command> + The timestamp of the packet. The presentation format of this timestamp + can be changed, see <xref linkend="ChWorkTimeFormatsSection"/>. + </para> + </listitem> + <listitem> + <para><command>Source</command> + The address where this packet is coming from. + </para> + </listitem> + <listitem> + <para><command>Destination</command> + The address where this packet is going to. + </para> + </listitem> + <listitem> + <para><command>Protocol</command> + The protocol name in a short (perhaps abbreviated) version. + </para> + </listitem> + <listitem> + <para><command>Info</command> + Additional information about the packet content. + </para> + </listitem> + </itemizedlist> + </para> + <para> + There is a context menu (right mouse click) available, see details in + <xref linkend="ChWorkPacketListPanePopUpMenu"/>. + </para> + </section> + + <section id="ChUsePacketDetailsPaneSection"><title>The "Packet Details" pane</title> + <para> + The packet details pane shows the current packet (selected in the "Packet List" + pane) in a more detailed form. + <figure id="ChUseEtherealDetailsPane"> + <title>The "Packet Details" pane</title> + <graphic entityref="EtherealDetailsPane" format="PNG"/> + </figure> + </para> + <para> + This pane shows the protocols and protocol fields of the packet selected + in the "Packet List" pane. The protocols and fields of the packet are + displayed using a tree, which can be expanded and collapsed. + </para> + <para> + There is a context menu (right mouse click) available, see details in + <xref linkend="ChWorkPacketDetailsPanePopUpMenu"/>. + </para> + <para> + Some protocol fields are specially displayed. + </para> + <itemizedlist> + <listitem> + <para> + <command>Generated fields</command> + Ethereal itself will generate additional protocol fields which are + surrounded by brackets. The information in these fields is derived from the + known context to other packets in the capture file. For example, Ethereal + is doing a sequence/acknowledge analysis of each TCP stream, + which is displayed in the [SEQ/ACK analysis] fields of the TCP protocol. + </para> + </listitem> + <listitem> + <para> + <command>Links</command> + If Ethereal detected a relationship to another packet in the capture file, + it will generate a link to that packet. Links are underlined and displayed + in blue. If double-clicked, Ethereal jumps to the corresponding packet. + </para> + </listitem> + </itemizedlist> + </section> + + <section id="ChUsePacketBytesPaneSection"><title>The "Packet Bytes" pane</title> + <para> + The packet bytes pane shows the data of the current packet (selected in the "Packet List" + pane) in a hexdump style. + <figure id="ChUseEtherealBytesPane"> + <title>The "Packet Bytes" pane</title> + <graphic entityref="EtherealBytesPane" format="PNG"/> + </figure> + </para> + <para> + As usual for a hexdump, the left side shows the offset in the packet data, + in the middle the packet data is shown in a hexadecimal representation and + on the right the corresponding ASCII characters (or . if not appropriate) + are displayed. + </para> + <para> + There is a context menu (right mouse click) available, see details in + <xref linkend="ChWorkPacketBytesPanePopUpMenu"/>. + </para> + <para> + Depending on the packet data, sometimes more than one page is available, + e.g. when Ethereal has reassembled some packets into a single chunk of + data, see <xref linkend="ChAdvReassemblySection"/>. In this case there are + some additional tabs shown at the bottom of the pane to let you select + the page you want to see. + <figure id="ChUseEtherealBytesPaneTabs"> + <title>The "Packet Bytes" pane with tabs</title> + <graphic entityref="EtherealBytesPaneTabs" format="PNG"/> + </figure> + </para> + <note><title>Note!</title> + <para> + The additional pages might contain data picked from multiple packets. + </para> + </note> + <para> + The context menu (right mouse click) of the tab labels will show a list of + all available pages. This can be helpful if the size in the pane is too + small for all the tab labels. + </para> + </section> + + <section id="ChUseStatusbarSection"><title>The Statusbar</title> + <para> + The statusbar displays informational messages. + </para> + <para> + In general, the left side will show context related information, while the + right side will show the current number of packets. + </para> + <para> + <figure id="ChUseEtherealStatusbarEmpty"> + <title>The initial Statusbar</title> + <graphic entityref="EtherealStatusbarEmpty" format="PNG"/> + </figure> + This statusbar is shown while no capture file is loaded, e.g. when + Ethereal is started. + </para> + <para> + <figure id="ChUseEtherealStatusbarLoaded"> + <title>The Statusbar with a loaded capture file</title> + <graphic entityref="EtherealStatusbarLoaded" format="PNG"/> + </figure> + The left side shows information about the capture file, its + name, its size and the elapsed time while it was being captured. + </para> + <para> + The right side shows the current number of packets in the + capture file. The following values are displayed: + <itemizedlist mark="bullet"> + <listitem> + <para><emphasis>P:</emphasis> the number of captured packets</para> + </listitem> + <listitem> + <para><emphasis>D:</emphasis> the number of packets currently being + displayed</para> + </listitem> + <listitem> + <para><emphasis>M:</emphasis> the number of marked packets</para> + </listitem> + </itemizedlist> + </para> + <para> + <figure id="ChUseEtherealStatusbarSelected"> + <title>The Statusbar with a selected protocol field</title> + <graphic entityref="EtherealStatusbarSelected" format="PNG"/> + </figure> + This is displayed if you have selected a protocol field from the + "Packet Details" pane. + </para> + <tip><title>Tip!</title> + <para> + The value between the brackets (in this example + <command>arp.opcode</command>) can be used as a display filter string, + representing the selected protocol field. + </para> + </tip> + </section> + +</chapter> +<!-- End of EUG Chapter 3 --> diff --git a/docbook/ug-src/EUG_chapter_work.xml b/docbook/ug-src/EUG_chapter_work.xml index d05f5bde75..a0a4455cc3 100644 --- a/docbook/ug-src/EUG_chapter_work.xml +++ b/docbook/ug-src/EUG_chapter_work.xml @@ -1,1381 +1,1383 @@ -<!-- EUG Chapter Work -->
-<chapter id="ChapterWork">
- <title>Working with captured packets</title>
-
- <section id="ChWorkViewPacketsSection"><title>Viewing packets you have captured</title>
- <para>
- Once you have captured some packets, or you have opened a previously
- saved capture file, you can view the packets that are displayed in
- the packet list pane by simply clicking on that packet in the
- packet list pane, which will bring up the selected packet in the
- tree view and byte view panes.
- </para>
- <para>
- You can then expand any part of the tree view by clicking on the
- <command>plus</command> sign (the symbol itself may vary) to the left of
- that part of the payload,
- and you can select individual fields by clicking on them in the tree
- view pane. An example with a TCP packet selected is shown in
- <xref linkend="ChWorkSelPack1"/>. It also has the Acknowledgment number
- in the TCP header selected, which shows up in the byte view as the
- selected bytes.
- <figure id="ChWorkSelPack1">
- <title>Ethereal with a TCP packet selected for viewing</title>
- <graphic entityref="EtherealPacketSelected1" format="PNG"/>
- </figure>
- </para>
- <para>
- You can also select and view packets the same way, while Ethereal is
- capturing, if you selected "Update list of packets in real time" in the
- Ethereal Capture Preferences dialog box.
- </para>
- <para>
- In addition, you can view individual packets in a separate window as
- shown in <xref linkend="ChWorkPacketSepView"/>. Do this by selecting the
- packet you are interested in in the packet list pane, and then
- select "Show Packet in New Windows" from the Display menu. This
- allows you to easily compare two or more packets.
- <figure id="ChWorkPacketSepView">
- <title>Viewing a packet in a separate window</title>
- <graphic entityref="EtherealPacketSepView" format="PNG"/>
- </figure>
- </para>
- <para>
- Finally, you can bring up a pop-up menu over either the "Packet List",
- "Packet Details" or "Packet Bytes" pane by clicking your right mouse button.
- </para>
- <para>
- The following table gives an overview of which functions are available
- in the panes, where to find the corresponding function in the menu, and
- a short description of each item.
- </para>
- <table id="PopupMenuTable">
- <title>Function overview of the pop-up menus</title>
- <tgroup cols="6">
- <colspec colnum="1" colwidth="80pt"/>
- <colspec colnum="2" colwidth="20pt"/>
- <colspec colnum="3" colwidth="20pt"/>
- <colspec colnum="4" colwidth="20pt"/>
- <colspec colnum="5" colwidth="80pt"/>
- <thead>
- <row>
- <entry>Item</entry>
- <entry>List</entry>
- <entry>Details</entry>
- <entry>Bytes</entry>
- <entry>Menu</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><command>Follow TCP stream</command></entry>
- <entry>X</entry>
- <entry>X</entry>
- <entry>X</entry>
- <entry>Analyze</entry>
- <entry>
- <para>View all the data on a TCP stream between a pair of nodes.</para>
- </entry>
- </row>
- <row>
- <entry><command>Decode As...</command></entry>
- <entry>X</entry>
- <entry>X</entry>
- <entry>X</entry>
- <entry>Analyze</entry>
- <entry>
- <para>.</para>
- </entry>
- </row>
- <row>
- <entry><command>Display Filters...</command></entry>
- <entry>X</entry>
- <entry>X</entry>
- <entry>X</entry>
- <entry>Analyze</entry>
- <entry>
- <para>Specify and manage filters.</para>
- </entry>
- </row>
- <row>
- <entry><command>Mark Packet</command></entry>
- <entry>X</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>Edit</entry>
- <entry>
- <para>Mark a packet.</para>
- </entry>
- </row>
- <row>
- <entry><command>Time Reference</command></entry>
- <entry>X</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>Edit</entry>
- <entry>
- <para>Set/reset and find time references.</para>
- </entry>
- </row>
- <row>
- <entry><command>Apply as Filter</command></entry>
- <entry>X</entry>
- <entry>X</entry>
- <entry>-</entry>
- <entry>Analyze</entry>
- <entry>
- <para>.</para>
- </entry>
- </row>
- <row>
- <entry><command>Prepare a Filter</command></entry>
- <entry>X</entry>
- <entry>X</entry>
- <entry>-</entry>
- <entry>Analyze</entry>
- <entry>
- <para>.</para>
- </entry>
- </row>
- <row>
- <entry><command>Coloring Rules...</command></entry>
- <entry>X</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>View</entry>
- <entry>
- <para>Colorize packets in the "Packet List" pane.</para>
- </entry>
- </row>
- <row>
- <entry><command>Print...</command></entry>
- <entry>X</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>File</entry>
- <entry>
- <para>Print packets.</para>
- </entry>
- </row>
- <row>
- <entry><command>Show Packet in New Window</command></entry>
- <entry>X</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>View</entry>
- <entry>
- <para>Display the selected packet in another window.</para>
- </entry>
- </row>
- <row>
- <entry><command>Resolve name</command></entry>
- <entry>-</entry>
- <entry>X</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>
- <para>Cause a name resolution to be performed for the selected packet,
- but NOT for every packet in the capture.</para>
- </entry>
- </row>
- <row>
- <entry><command>Go to Corresponding Packet</command></entry>
- <entry>-</entry>
- <entry>X</entry>
- <entry>-</entry>
- <entry>Go</entry>
- <entry>
- <para>If the selected field has a packet number in it, go to it. The
- corresponding packet will often be a response which is requested by
- this packet, or the request for which this packet is a response.
- </para>
- </entry>
- </row>
- <row>
- <entry><command>Export Selected Packet Bytes...</command></entry>
- <entry>-</entry>
- <entry>X</entry>
- <entry>X</entry>
- <entry>File->Export</entry>
- <entry>
- <para>Export raw packet bytes to a binary file.</para>
- </entry>
- </row>
- <row>
- <entry><command>Protocol Preferences...</command></entry>
- <entry>-</entry>
- <entry>X</entry>
- <entry>-</entry>
- <entry>Edit</entry>
- <entry>
- <para>The menu item takes you to the preferences dialog and selects
- the page corresponding to the protocol if there are settings
- associated with the highlighted field. More information on preferences
- can be found in <xref linkend="ChCustProtocolsPrefPages"/>.
- </para>
- </entry>
- </row>
- <row>
- <entry><command>Collapse All</command></entry>
- <entry>-</entry>
- <entry>X</entry>
- <entry>-</entry>
- <entry>View</entry>
- <entry>
- <para>
- Ethereal keeps a list of all the protocol subtrees that are
- expanded, and uses it to ensure that the correct subtrees
- are expanded when you display a packet. This menu item
- collapses the tree view of all packets in the capture list.
- </para>
- </entry>
- </row>
- <row>
- <entry><command>Expand All</command></entry>
- <entry>-</entry>
- <entry>X</entry>
- <entry>-</entry>
- <entry>View</entry>
- <entry>
- <para>Expand all subtrees in all packets in the capture.
- </para>
- </entry>
- </row>
- <row>
- <entry><command>Expand Tree</command></entry>
- <entry>-</entry>
- <entry>X</entry>
- <entry>-</entry>
- <entry>View</entry>
- <entry>
- <para>Expand the currently selected subtree.
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <para>
- <figure id="ChWorkPacketListPanePopUpMenu">
- <title>Pop-up menu of "Packet List" pane</title>
- <graphic entityref="EtherealPacketPanePopupMenu" format="PNG"/>
- </figure>
- <variablelist>
- <varlistentry><term><command>Follow TCP Stream</command></term>
- <listitem>
- <para>
- This menu item is the same as the Analyze menu item of
- the same name. It allows you to view all the data on a TCP
- stream between a pair of nodes.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>Decode As...</command></term>
- <listitem>
- <para>
- This menu item is the same as the Analyze menu item of the
- same name.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>Display Filters...</command></term>
- <listitem>
- <para>
- This menu item is the same as the Analyze menu item of the same
- name. It allows you to specify and manage display filters.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>Mark Packet</command></term>
- <listitem>
- <para>
- This menu item is the same as the Edit menu item of the same
- name. It allows you to mark a packet.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>Time Reference</command></term>
- <listitem>
- <para>
- This menu item is the same as the Edit menu items of the same
- name. It allows you to set and work with time references.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>Apply as Filter</command></term>
- <listitem>
- <para>
- This menu item is the same as the Analyze menu items of the same
- name.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>Prepare a Filter</command></term>
- <listitem>
- <para>
- This menu item is the same as the Analyze menu items of the same
- name.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><command>Coloring Rules...</command></term>
- <listitem>
- <para>
- This menu item is the same as the View menu item of the
- same name. It allows you to colorize packets in the packet
- list pane.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>Print...</command></term>
- <listitem>
- <para>
- This menu item is the same as the File menu item of the same
- name. It allows you to print packets.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><command>Show Packet in New Window</command></term>
- <listitem>
- <para>
- This menu item is the same as the View menu item of the
- same name. It allows you to display the selected packet in
- another window.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
- <para>
- <figure id="ChWorkPacketDetailsPanePopUpMenu">
- <title>Pop-up menu of "Packet Details" pane</title>
- <graphic entityref="EtherealDetailsPanePopupMenu" format="PNG"/>
- </figure>
- <variablelist>
- <varlistentry><term><command>Follow TCP Stream</command></term>
- <listitem>
- <para>
- This menu item is the same as the Analyze menu item of the
- same name. It allows you to view all the data on a TCP stream
- between a pair of nodes.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>Decode As...</command></term>
- <listitem>
- <para>
- This menu item is the same as the Analyze menu item of the
- same name.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>Display Filters...</command></term>
- <listitem>
- <para>
- This menu item is the same as the Analyze menu item of the same
- name. It allows you to specify and manage filters.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>Resolve Name</command></term>
- <listitem>
- <para>
- This menu item causes name resolution to be performed for
- the selected packet, but NOT every packet in the capture.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>Go to Corresponding Packet</command></term>
- <listitem>
- <para>
- If the selected field has a corresponding packet, go to it.
- Corresponding packets will usually be a request/response packet pair
- or such.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>Export Selected Packet Bytes...</command></term>
- <listitem>
- <para>
- This menu item is the same as the File menu item of the same
- name. It allows you to export raw packet bytes to a binary file.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>Protocol Properties...</command></term>
- <listitem>
- <para>
- The menu item takes you to the properties dialog and selects the
- page corresponding to the protocol if there are properties
- associated with the highlighted field.
- More information on preferences can be found in
- <xref linkend="ChCustGUIPrefPage"/>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>Apply as Filter</command></term>
- <listitem>
- <para>
- This menu item is the same as the Analyze menu items of the same
- name.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>Prepare a Filter</command></term>
- <listitem>
- <para>
- This menu item is the same as the Analyze menu items of the same
- name.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>Collapse All</command></term>
- <listitem>
- <para>
- Ethereal keeps a list of all the protocol subtrees that are
- expanded, and uses it to ensure that the correct subtrees
- are expanded when you display a packet. This menu item
- collapses the tree view of all packets in the capture list.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>Expand All</command></term>
- <listitem>
- <para>
- This menu item expands all subtrees in all packets in the
- capture.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>Expand Tree</command></term>
- <listitem>
- <para>
- This menu item expands the currently selected subtree.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
- <para>
- <figure id="ChWorkPacketBytesPanePopUpMenu">
- <title>Pop-up menu of "Packet Bytes" pane</title>
- <graphic entityref="EtherealBytesPanePopupMenu" format="PNG"/>
- </figure>
- <variablelist>
- <varlistentry><term><command>Follow TCP Stream</command></term>
- <listitem>
- <para>
- This menu item is the same as the Analyze menu item of the
- same name. It allows you to view all the data on a TCP stream
- between a pair of nodes.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>Decode As...</command></term>
- <listitem>
- <para>
- This menu item is the same as the Analyze menu item of the
- same name.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>Display Filters...</command></term>
- <listitem>
- <para>
- This menu item is the same as the Analyze menu item of the same
- name. It allows you to specify and manage filters.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>Export Selected Packet Bytes...</command></term>
- <listitem>
- <para>
- This menu item is the same as the File menu item of the same
- name. It allows you to export raw packet bytes to a binary file.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
- </section>
-
- <section id="ChWorkDisplayFilterSection"><title>Filtering packets while viewing</title>
- <para>
- Ethereal has two filtering languages: One used when capturing
- packets, and one used when displaying packets. In this section we
- explore that second type of filter: Display filters. The first one
- has already been dealt with in <xref linkend="ChCapCaptureFilterSection"/>.
- </para>
- <para>
- Display filters allow you to concentrate on the packets you are
- interested in. They allow you to select packets by:
- <itemizedlist>
- <listitem><para>Protocol</para></listitem>
- <listitem><para>The presence of a field</para></listitem>
- <listitem><para>The values of fields</para></listitem>
- <listitem><para>A comparison between fields</para></listitem>
- <listitem><para>... and a lot more!</para></listitem>
- </itemizedlist>
- </para>
- <para>
- To select packets based on protocol type, simply type the protocol you
- are interested in in the <command>Filter:</command> field in the filter
- toolbar of the Ethereal window and press enter to initiate
- the filter. <xref linkend="ChWorkTCPFilter"/> shows an example of what
- happens when you type <command>tcp</command> in the filter field.
- </para>
- <note>
- <title>Note!</title>
- <para>
- All protocol and field names are entered in lowercase. Also, don't
- forget to press enter after entering the filter expression.
- </para>
- </note>
- <figure id="ChWorkTCPFilter"><title>Filtering on the TCP protocol</title>
- <graphic entityref="EtherealFilterTCP" format="JPG"/>
- </figure>
- <para>
- As you might have noticed, only packets of the TCP protocol are displayed
- now (e.g. packets 1-10 are hidden). The packet numbering will remain as
- before, so the first packet shown is now packet number 11.
- </para>
- <note>
- <title>Note!</title>
- <para>
- When using a display filter, all packets remain in the capture file.
- The display filter only changes the display of the capture file and
- not its content!
- </para>
- </note>
- <para>
- You can filter on any protocol that Ethereal understands.
- You can also filter on any field that a dissector adds to the tree
- view, but only if the dissector has added an abbreviation for the
- field. A list of such fields is available in the Ethereal in the
- <command>Add Expression...</command> dialog box. You can find more
- information on the <command>Add Expression...</command> dialog box
- in <xref linkend="ChWorkFilterAddExpressionSection"/>.
- </para>
- <para>
- For example, to narrow the packet list pane down to only those
- packets to or from the IP address 192.168.0.1, use
- <command>ip.addr==192.168.0.1</command>.
- </para>
- <note>
- <title>Note!</title>
- <para>
- To remove the filter, click on the <command>Clear</command> button
- to the right of the filter field.
- </para>
- </note>
- </section>
-
- <section id="ChWorkBuildDisplayFilterSection">
- <title>Building display filter expressions</title>
- <para>
- Ethereal provides a simple but powerful display filter language that you
- can build quite complex filter expressions with. You can compare
- values in packets as well as combine expressions into more
- specific expressions. The following sections provide more
- information on doing this.
- </para>
- <section>
- <title>Display filter fields</title>
- <para>
- Every field in the packet details pane can be used as a filter
- string, this will result in showing only the packets where this field
- exists. For example: the
- filter string: <command>tcp</command> will show all packets containing the
- tcp protocol.
- </para>
- <para>
- There is a complete list of all filter fields available
- through the menu item "Help/Supported Protocols" in the page "Display Filter
- Fields" of the upcoming dialog.
- </para>
- <para>
- XXX - add some more info here and a link to the statusbar info.
- </para>
- </section>
- <section>
- <title>Comparing values</title>
- <para>
- You can build display filters that compare values using a number
- of different comparison operators. They are shown in
- <xref linkend="DispCompOps"/>.
- </para>
- <tip><title></title>
- <para>
- You can use English and C-like terms in the same way, they can even be
- mixed in a filter string!
- </para>
- </tip>
- <table id="DispCompOps">
- <title>Display Filter comparison operators</title>
- <tgroup cols="3">
- <colspec colnum="1" colwidth="50pt"/>
- <colspec colnum="2" colwidth="50pt"/>
- <thead>
- <row>
- <entry>English</entry>
- <entry>C-like</entry>
- <entry>Description and example</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>eq</entry>
- <entry><programlisting>==</programlisting></entry>
- <entry><para>
- <command>Equal</command></para><para>
- <programlisting>ip.addr==10.0.0.5</programlisting>
- </para></entry>
- </row>
- <row>
- <entry>ne</entry>
- <entry><programlisting>!=</programlisting></entry>
- <entry><para>
- <command>Not equal</command></para><para>
- <programlisting>ip.addr!=10.0.0.5</programlisting>
- </para></entry>
- </row>
- <row>
- <entry>gt</entry>
- <entry><programlisting>></programlisting></entry>
- <entry><para>
- <command>Greater than</command></para><para>
- <programlisting>frame.pkt_len > 10</programlisting>
- </para></entry>
- </row>
- <row>
- <entry>lt</entry>
- <entry><programlisting><</programlisting></entry>
- <entry><para><command>Less than</command></para><para>
- <programlisting>frame.pkt_len < 128</programlisting>
- </para></entry>
- </row>
- <row>
- <entry>ge</entry>
- <entry><programlisting>>=</programlisting></entry>
- <entry><para>
- <command>Greater than or equal to</command></para><para>
- <programlisting>frame.pkt_len ge 0x100</programlisting>
- </para></entry>
- </row>
- <row>
- <entry>le</entry>
- <entry><programlisting><=</programlisting></entry>
- <entry><para>
- <command>Less than or equal to</command></para><para>
- <programlisting>frame.pkt_len <= 0x20</programlisting>
- </para></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <para>
- In addition, all protocol fields are typed.
- <xref linkend="ChWorkFieldTypes"/> provides a list of the types and
- example of how to express them.
- <table id="ChWorkFieldTypes">
- <title>Display Filter Field Types</title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Type</entry>
- <entry>Example</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- Unsigned integer (8-bit, 16-bit, 24-bit, 32-bit)
- </entry>
- <entry><para>
- You can express integers in decimal, octal, or
- hexadecimal. The following display filters are
- equivalent:
- <programlisting>
-ip.len le 1500
-ip.len le 02734
-ip.len le 0x436
- </programlisting>
- </para></entry>
- </row>
- <row>
- <entry>
- Signed integer (8-bit, 16-bit, 24-bit, 32-bit)
- </entry>
- <entry></entry>
- </row>
- <row>
- <entry>Boolean</entry>
- <entry><para>
- A boolean field is present in the protocol decode
- only if its value is true. For example,
- <command>tcp.flags.syn</command> is present, and
- thus true, only if the SYN flag is present in a
- TCP segment header.</para><para>
- Thus the filter expression
- <command>tcp.flags.syn</command> will select only
- those packets for which this flag exists, that is,
- TCP segments where the segment header contains the
- SYN flag. Similarly, to find source-routed token
- ring packets, use a filter expression of
- <command>tr.sr</command>.
- </para></entry>
- </row>
- <row>
- <entry>Ethernet address (6 bytes)</entry>
- <entry>eth.addr == ff:ff:ff:ff:ff:ff</entry>
- </row>
- <row>
- <entry>IPv4 address</entry>
- <entry>ip.addr == 192.168.0.1</entry>
- </row>
- <row>
- <entry>IPv6 address</entry>
- <entry> </entry>
- </row>
- <row>
- <entry>IPX network number</entry>
- <entry> </entry>
- </row>
- <row>
- <entry>String (text)</entry>
- <entry> </entry>
- </row>
- <row>
- <entry>
- Double-precision floating point number
- </entry>
- <entry> </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </para>
- </section>
- <section>
- <title>Combining expressions</title>
- <para>
- You can combine filter expressions in Ethereal using the
- logical operators shown in <xref linkend="FiltLogOps"/>
- </para>
- <table id="FiltLogOps">
- <title>Display Filter Logical Operations</title>
- <tgroup cols="3">
- <colspec colnum="1" colwidth="50pt"/>
- <colspec colnum="2" colwidth="50pt"/>
- <thead>
- <row>
- <entry>English</entry>
- <entry>C-like</entry>
- <entry>Description and example</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>and</entry>
- <entry>&&</entry>
- <entry><para>
- <command>Logical AND</command></para><para>
- <programlisting>ip.addr==10.0.0.5 and tcp.flags.fin</programlisting>
- </para></entry>
- </row>
- <row>
- <entry>or</entry>
- <entry>||</entry>
- <entry><para>
- <command>Logical OR</command></para><para>
- <programlisting>ip.addr==10.0.0.5 or ip.addr==192.1.1.1</programlisting>
- </para></entry>
- </row>
- <row>
- <entry>xor</entry>
- <entry>^^</entry>
- <entry><para>
- <command>Logical XOR</command></para><para>
- <programlisting>tr.dst[0:3] == 0.6.29 xor tr.src[0:3] == 0.6.29</programlisting>
- </para></entry>
- </row>
- <row>
- <entry>not</entry>
- <entry>!</entry>
- <entry><para>
- <command>Logical NOT</command></para><para>
- <programlisting>not llc</programlisting>
- </para></entry>
- </row>
- <row>
- <entry>[...]</entry>
- <entry></entry>
- <entry><para>
- <command>Substring Operator</command></para><para>
- Ethereal allows you to select subsequences of a
- sequence in rather elaborate ways. After a label you
- can place a pair of brackes [] containing a comma
- separated list of range specifiers. </para><para>
- <programlisting>eth.src[0:3] == 00:00:83</programlisting></para><para>
- The example above uses the n:m format to specify a
- single range. In this case n is the beginning offset
- and m is the length of the range
- being specified.</para><para>
- <programlisting>
-eth.src[1-2] == 00:83
- </programlisting></para><para>
- The example above uses the n-m format to specify a
- single range. In this case n is the beginning offset
- and m is the ending offset. </para><para>
- <programlisting>eth.src[:4] == 00:00:83:00</programlisting></para><para>
- The example above uses the :m format, which takes
- everything from the beginning of a sequence to offset m.
- It is equivalent to 0:m</para><para>
- <programlisting>eth.src[4:] == 20:20</programlisting></para><para>
- The example above uses the n: format, which takes
- everything from offset n to the end of the
- sequence. </para><para>
- <programlisting>eth.src[2] == 83</programlisting></para><para>
- The example above uses the n format to specify a
- single range. In this case the element in the
- sequence at offset n is selected. This is equivalent
- to n:1.</para><para>
- <programlisting>eth.src[0:3,1-2,:4,4:,2] ==
-00:00:83:00:83:00:00:83:00:20:20:83</programlisting></para><para>
- Ethereal allows you to string together single ranges
- in a comma separated list to form compound ranges as
- shown above.
- </para></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
- <section><title>A common mistake</title>
- <para>
- Often people use a filter string to display something like
- <command>ip.addr == 1.2.3.4</command> which will display all packets
- containing the IP address 1.2.3.4.
- </para>
- <para>
- Then they use <command>ip.addr != 1.2.3.4</command> to see all packets
- not containing the IP address 1.2.3.4 in it. Unfortunately, this does
- <command>not</command> do the expected.
- </para>
- <para>
- Instead, that expression will even be true for packets where either
- source or destination IP address equals 1.2.3.4. The reason for this,
- is that the expression <command>ip.addr != 1.2.3.4</command> must be read as "the
- packet contains a field named ip.addr with a value
- different from 1.2.3.4". As an IP datagram contains both a source and
- a destination address, the expression will evaluate to true whenever
- at least one of the two addresses differs from 1.2.3.4.
- </para>
- <para>
- If you want to
- filter out all packets containing IP datagrams to or from IP address
- 1.2.3.4, then the correct filter is <command>!(ip.addr == 1.2.3.4)</command> as it
- reads "show me all the packets for which it is not true
- that a field named ip.addr exists with a value of 1.2.3.4", or in
- other words, "filter out all packets for which there are
- no occurrences of a field named ip.addr with the value 1.2.3.4".
- </para>
- </section>
- </section>
-
- <section id="ChWorkFilterAddExpressionSection">
- <title>The "Filter Expression" dialog box</title>
- <para>
- When you are accustomed to Ethereal's filtering system and know what
- labels you wish to use in your filters it can be very quick to
- simply type a filter string. However if you are new to Ethereal or
- are working with a slightly unfamiliar protocol it can be very
- confusing to try to figure out what to type. The Filter Expression
- dialog box helps with this.
- </para>
- <tip><title>Tip!</title>
- <para>
- The "Filter Expression" dialog box is an excellent way to learn how to
- write Ethereal display filter strings.
- </para>
- </tip>
- <figure id="ChWorkFilterAddExpression1">
- <title>The "Filter Expression" dialog box</title>
- <graphic entityref="EtherealFilterAddExpression" format="PNG"/>
- </figure>
- <para>
- When you first bring up the Filter Expression dialog box you are shown a
- tree list of field names, organized by protocol, and a box for
- selecting a relation.
- </para>
- <variablelist>
- <varlistentry><term><command>Field Name</command></term>
- <listitem>
- <para>
- Select a protocol field from the protocol field tree.
- Every protocol with filterable fields is listed at the
- top level. By clicking on the "+" next to a protocol name
- you can get a list of the field names available for filtering
- for that protocol.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>Relation</command></term>
- <listitem>
- <para>
- Select a relation from the list of available relation.
- The <command>is present</command> is a unary relation which
- is true if the selected field is present in a packet. All
- other listed relations are binary relations which require additional
- data (e.g. a <command>Value</command> to match) to complete.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- <para>
- When you select a field from the field name list and select a
- binary relation (such as the equality relation ==) you will be
- given the opportunity to enter a value, and possibly some range
- information.
- </para>
- <variablelist>
- <varlistentry><term><command>Value</command></term>
- <listitem>
- <para>
- You may enter an appropriate value in the
- <command>Value</command> text box. The <command>Value</command>
- will also indicate the type of value for the
- <command>field name</command> you have selected ( like
- character string ).
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>Predefined values</command></term>
- <listitem>
- <para>
- Some of the protocol fields have predefined values available, much like
- enum's in C. If the selected protocol field has such values defined, you
- can choose it here.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>Range</command></term>
- <listitem>
- <para>
- XXX - add an explanation here!
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>OK</command></term>
- <listitem>
- <para>
- When you have built a satisfactory expression click
- <command>OK</command> and a filter string will be
- built for you.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>Cancel</command></term>
- <listitem>
- <para>
- You can leave the <command>Add Expression...</command> dialog
- box without any effect by clicking the <command>Cancel</command>
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
-
- <section id="ChWorkDefineFilterSection"><title>Defining and saving filters</title>
- <para>
- You can define filters with Ethereal and give them labels for
- later use. This can save time in remembering and retyping some of
- the more complex filters you use.
- </para>
- <para>
- To define a new filter or edit an existing filter, select the
- <command>Capture Filters...</command> menu item from the Capture menu
- or the <command>Display Filters...</command> menu item from the Analyze
- menu. Ethereal will then pop up the Filters dialog as shown in
- <xref linkend="FiltersDialog"/>.
- </para>
- <note>
- <title>Note!</title>
- <para>
- The mechanisms for defining and saving capture filters and display
- filters are almost identical. So both will be described here,
- differences between these two will be marked as such.
- </para>
- </note>
- <warning><title>Warning!</title>
- <para>
- You must use <command>Save</command> to save your filters permanently.
- <command>Ok</command> or <command>Apply</command> will not save the filters,
- so they will be lost when you close Ethereal.
- </para>
- </warning>
- <figure id="FiltersDialog">
- <title>The "Capture Filters" and "Display Filters" dialog boxes</title>
- <graphic entityref="EtherealFilters" format="PNG"/>
- </figure>
- <para>
- <variablelist>
- <varlistentry><term><command>New</command></term>
- <listitem>
- <para>
- This button adds a new filter to the list of filters. The currently
- entered values from Filter name and Filter string will be used. If
- any of these fields are empty, it will be set to "new".
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>Delete</command></term>
- <listitem>
- <para>
- This button deletes the selected filter. It will be greyed out, if no
- filter is selected.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>Filter</command></term>
- <listitem>
- <para>
- You can select a filter from this list (which will fill in the
- filter name and filter string in the fields down the bottom of the
- dialog box).
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>Filter name:</command></term>
- <listitem>
- <para>
- You can change the name of the currently selected filter here.
- </para>
- <note><title>Note!</title>
- <para>
- The filter name will only be used in this dialog to identify the
- filter for your convenience, it will not be used elsewhere. You can
- add multiple filters with the same name, but this is not very useful.
- </para>
- </note>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>Filter string:</command></term>
- <listitem>
- <para>
- You can change the filter string of the currently selected filter here.
- Display Filter only: the string will be syntax checked while you are
- typing.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>Add Expression...</command></term>
- <listitem>
- <para>
- Display Filter only: This button brings up the Add Expression
- dialog box which assists in building filter strings. You can find
- more information about the Add Expression dialog in
- <xref linkend="ChWorkFilterAddExpressionSection"/>
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>OK</command></term>
- <listitem>
- <para>
- Display Filter only: This button applies the selected filter to the
- current display and closes the dialog.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>Apply</command></term>
- <listitem>
- <para>
- Display Filter only: This button applies the selected filter to the
- current display, and keeps the dialog open.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>Save</command></term>
- <listitem>
- <para>
- Save the current settings in this dialog. The file location and
- format is explained in <xref linkend="AppFiles"/>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term><command>Close</command></term>
- <listitem>
- <para>
- Close this dialog. This will discard unsaved settings.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
- </section>
-
- <section id="ChWorkFindPacketSection"><title>Finding packets</title>
- <para>
- You can easily find packets once you have captured some packets or
- have read in a previously saved capture file. Simply select the
- <command>Find Packet...</command> menu item from the
- <command>Edit</command> menu. Ethereal will pop up the dialog box
- shown in <xref linkend="ChWorkFindPacketDialog"/>.
- </para>
- <section><title>The "Find Packet" dialog box</title>
- <figure id="ChWorkFindPacketDialog">
- <title>The "Find Packet" dialog box</title>
- <graphic entityref="EtherealFindPacket" format="PNG"/>
- </figure>
- <para>
- You might first select the kind of thing to search for:
- <itemizedlist>
- <listitem>
- <para>
- <command>Display filter</command>
- </para>
- <para>
- Simply enter a display filter string into the
- <command>Filter:</command> field, select a direction, and click on OK.
- </para>
- <para>
- For example, to find the three way handshake for a connection from
- host 192.168.0.1, use the following filter string:
- <programlisting>ip.addr==192.168.0.1 and tcp.flags.syn</programlisting>
- For more details on display filters, see <xref linkend="ChWorkDisplayFilterSection"/>
- </para>
- </listitem>
- <listitem>
- <para>
- <command>Hex Value</command>
- </para>
- <para>
- Search for a specific byte sequence in the packet data.
- </para>
- <para>
- For example, use "00:00" to find the next packet including two
- null bytes in the packet data.
- </para>
- </listitem>
- <listitem>
- <para>
- <command>String</command>
- </para>
- <para>
- Find a string in the packet data, with various options.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- The value to be found will by syntax checked while you type it in. If the
- syntax check of your value succeeded, the background of the entry field
- will turn green, if it fails, it will turn red.
- </para>
- <para>
- You can choose the direction to be searched for:
- <itemizedlist>
- <listitem>
- <para><command>Up</command></para>
- <para>Search upwards in the packet list (decreasing packet numbers).</para>
- </listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem>
- <para><command>Down</command></para>
- <para>Search downwards in the packet list (increasing packet numbers).</para>
- </listitem>
- </itemizedlist>
- </para>
- </section>
- <section><title>The "Find Next" command</title>
- <para>
- "Find Next" will continue searching with the same options like in the last
- "Find Packet" run.
- </para>
- </section>
- <section><title>The "Find Previous" command</title>
- <para>
- "Find Previous" will do the same thing as "Find Next", but with reverse
- search direction.
- </para>
- </section>
- </section>
-
- <section id="ChWorkGoToPacketSection"><title>Go to a specific packet</title>
- <para>
- You can easily jump to specific packets with one of the menu items in the
- Go menu.
- </para>
- <section><title>The "Go to Packet" dialog box</title>
- <figure id="ChWorkGoToPacketDialog">
- <title>The "Go To Packet" dialog box</title>
- <graphic entityref="EtherealGoToPacket" format="PNG"/>
- </figure>
- <para>
- This dialog box will let you enter a packet number. When you press
- <command>OK</command>, Ethereal will jump to that packet.
- </para>
- </section>
- <section><title>The "Go to Corresponding Packet" command</title>
- <para>
- If a protocol field is selected, which points to another packet in the
- capture file, this command will jump to that packet.
- </para>
- <note><title>Note!</title>
- <para>
- As these protocol fields now work like links (just as in your
- Web browser), it's easier simply to double-click on the field to jump
- to the corresponding field.
- </para>
- </note>
- </section>
- <section><title>The "Go to First Packet" command</title>
- <para>
- This command will simply jump to the first packet displayed.
- </para>
- </section>
- <section><title>The "Go to Last Packet" command</title>
- <para>
- This command will simply jump to the last packet displayed.
- </para>
- </section>
- </section>
-
- <section id="ChWorkMarkPacketSection"><title>Marking packets</title>
- <para>
- You can mark packets in the "Packet List" pane. A marked packet will
- be shown with black background, regardless of the coloring rules set.
- Marking a packet can be useful to find it later while analyzing in a large
- capture file.
- </para>
- <warning><title>Warning!</title>
- <para>
- The packet marks are not stored in the capture file or anywhere else,
- so all packet marks will be lost if you close the capture file.
- </para>
- </warning>
- <para>
- You can use packet marking to control the output of packets when
- saving/exporting/printing. To do so, an option in the packet range is
- available, see <xref linkend="ChIOPacketRangeSection"/>.
- </para>
- <para>
- There are three functions to manipulate the marked state of a packet:
- <itemizedlist>
- <listitem>
- <para>
- <command>Mark packet</command> toggle the marked state of a single packet.
- </para>
- </listitem>
- <listitem>
- <para>
- <command>Mark all packets</command> set the mark state of all packets.
- </para>
- </listitem>
- <listitem>
- <para>
- <command>Unmark all packets</command> reset the mark state of all packets.
- </para>
- </listitem>
- </itemizedlist>
- These mark function are available from the "Edit" menu, and the "Mark packet"
- function is also available from the popup menu of the "Packet List" pane.
- </para>
- </section>
-
- <section id="ChWorkTimeFormatsSection"><title>Time display formats and time
- references</title>
- <para>
- While packets are captured, each packet is timestamped. These timestamps
- will be saved to the capture file, so they will be available for later
- analysis.
- </para>
- <para>
- When the packets are displayed, the presentation of these timestamps can
- be chosen by the user. There are four presentation formats available:
- <itemizedlist>
- <listitem><para><command>Time of Day</command>, e.g. 20:02:48.863096
- The absolute time of the day when the packet was captured.</para>
- </listitem>
- <listitem><para><command>Date and Time of Day</command>, e.g. 2004-06-22 20:02:48.863096
- The absolute date and time of the day when the packet was captured.</para>
- </listitem>
- <listitem><para><command>Seconds Since Beginning of Capture</command>, e.g. 123.299139
- The time relative to the start of the capture file or the first
- "Time Reference" before this packet (see <xref
- linkend="ChWorkTimeReferencePacketSection"/>).</para>
- </listitem>
- <listitem><para><command>Seconds Since Previous Packet</command>, e.g. 1.162423
- The time relative to the previous packet.</para>
- </listitem>
- </itemizedlist>
- The time format can be selected from the View menu, see
- <xref linkend="ChUseEtherealViewMenu"/>.
- </para>
- <para>
- XXX - how is the GMT / localtime thing handled.
- </para>
- <section id="ChWorkTimeReferencePacketSection">
- <title>Packet time referencing</title>
- <para>
- The user can set time references to packets. A time reference is the
- starting point for all subsequent packet time calculations. It will be
- useful, if you want to see the time values relative to a special packet,
- e.g. the start of a new request. It's possible to set multiple time
- references in the capture file.
- </para>
- <warning><title>Warning!</title>
- <para>
- The time references will not be saved permanently and will be lost when
- you close the capture file.
- </para>
- </warning>
- <note><title>Note!</title>
- <para>
- Time referencing will only be useful, if the time display format is set to
- "Seconds Since Beginning of Capture". If one of the other time display
- formats are used, time referencing will have no effect (and will make no
- sense either).
- </para>
- </note>
- <para>
- To work with time references, choose one of the "Time Reference" items
- in the "Edit" menu , see <xref linkend="ChUseEditMenuSection"/>, or from
- the popup menu of the "Packet List" pane.
- </para>
- <itemizedlist>
- <listitem><para><command>Set Time Reference (toggle)</command>
- Toggles the time reference state of the currently selected
- packet to on or off.</para>
- </listitem>
- <listitem><para><command>Find Next</command>
- Find the next time referenced packet in the "Packet List" pane.
- </para>
- </listitem>
- <listitem><para><command>Find Previous</command>
- Find the previous time referenced packet in the "Packet List"
- pane.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- <figure id="ChWorkTimeReference">
- <title>Ethereal showing a time referenced packet</title>
- <graphic entityref="EtherealTimeReference" format="PNG"/>
- </figure>
- </para>
- <para>
- A time referenced packet will be marked with the string *REF* in the Time
- column (see packet number 10). All subsequent packets will show the time
- since the last time reference.
- </para>
- </section>
- </section>
-
-</chapter>
-<!-- End of EUG Chapter Work -->
-
+<!-- EUG Chapter Work --> +<!-- $Id$ --> + +<chapter id="ChapterWork"> + <title>Working with captured packets</title> + + <section id="ChWorkViewPacketsSection"><title>Viewing packets you have captured</title> + <para> + Once you have captured some packets, or you have opened a previously + saved capture file, you can view the packets that are displayed in + the packet list pane by simply clicking on that packet in the + packet list pane, which will bring up the selected packet in the + tree view and byte view panes. + </para> + <para> + You can then expand any part of the tree view by clicking on the + <command>plus</command> sign (the symbol itself may vary) to the left of + that part of the payload, + and you can select individual fields by clicking on them in the tree + view pane. An example with a TCP packet selected is shown in + <xref linkend="ChWorkSelPack1"/>. It also has the Acknowledgment number + in the TCP header selected, which shows up in the byte view as the + selected bytes. + <figure id="ChWorkSelPack1"> + <title>Ethereal with a TCP packet selected for viewing</title> + <graphic entityref="EtherealPacketSelected1" format="PNG"/> + </figure> + </para> + <para> + You can also select and view packets the same way, while Ethereal is + capturing, if you selected "Update list of packets in real time" in the + Ethereal Capture Preferences dialog box. + </para> + <para> + In addition, you can view individual packets in a separate window as + shown in <xref linkend="ChWorkPacketSepView"/>. Do this by selecting the + packet you are interested in in the packet list pane, and then + select "Show Packet in New Windows" from the Display menu. This + allows you to easily compare two or more packets. + <figure id="ChWorkPacketSepView"> + <title>Viewing a packet in a separate window</title> + <graphic entityref="EtherealPacketSepView" format="PNG"/> + </figure> + </para> + <para> + Finally, you can bring up a pop-up menu over either the "Packet List", + "Packet Details" or "Packet Bytes" pane by clicking your right mouse button. + </para> + <para> + The following table gives an overview of which functions are available + in the panes, where to find the corresponding function in the menu, and + a short description of each item. + </para> + <table id="PopupMenuTable"> + <title>Function overview of the pop-up menus</title> + <tgroup cols="6"> + <colspec colnum="1" colwidth="80pt"/> + <colspec colnum="2" colwidth="20pt"/> + <colspec colnum="3" colwidth="20pt"/> + <colspec colnum="4" colwidth="20pt"/> + <colspec colnum="5" colwidth="80pt"/> + <thead> + <row> + <entry>Item</entry> + <entry>List</entry> + <entry>Details</entry> + <entry>Bytes</entry> + <entry>Menu</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><command>Follow TCP stream</command></entry> + <entry>X</entry> + <entry>X</entry> + <entry>X</entry> + <entry>Analyze</entry> + <entry> + <para>View all the data on a TCP stream between a pair of nodes.</para> + </entry> + </row> + <row> + <entry><command>Decode As...</command></entry> + <entry>X</entry> + <entry>X</entry> + <entry>X</entry> + <entry>Analyze</entry> + <entry> + <para>.</para> + </entry> + </row> + <row> + <entry><command>Display Filters...</command></entry> + <entry>X</entry> + <entry>X</entry> + <entry>X</entry> + <entry>Analyze</entry> + <entry> + <para>Specify and manage filters.</para> + </entry> + </row> + <row> + <entry><command>Mark Packet</command></entry> + <entry>X</entry> + <entry>-</entry> + <entry>-</entry> + <entry>Edit</entry> + <entry> + <para>Mark a packet.</para> + </entry> + </row> + <row> + <entry><command>Time Reference</command></entry> + <entry>X</entry> + <entry>-</entry> + <entry>-</entry> + <entry>Edit</entry> + <entry> + <para>Set/reset and find time references.</para> + </entry> + </row> + <row> + <entry><command>Apply as Filter</command></entry> + <entry>X</entry> + <entry>X</entry> + <entry>-</entry> + <entry>Analyze</entry> + <entry> + <para>.</para> + </entry> + </row> + <row> + <entry><command>Prepare a Filter</command></entry> + <entry>X</entry> + <entry>X</entry> + <entry>-</entry> + <entry>Analyze</entry> + <entry> + <para>.</para> + </entry> + </row> + <row> + <entry><command>Coloring Rules...</command></entry> + <entry>X</entry> + <entry>-</entry> + <entry>-</entry> + <entry>View</entry> + <entry> + <para>Colorize packets in the "Packet List" pane.</para> + </entry> + </row> + <row> + <entry><command>Print...</command></entry> + <entry>X</entry> + <entry>-</entry> + <entry>-</entry> + <entry>File</entry> + <entry> + <para>Print packets.</para> + </entry> + </row> + <row> + <entry><command>Show Packet in New Window</command></entry> + <entry>X</entry> + <entry>-</entry> + <entry>-</entry> + <entry>View</entry> + <entry> + <para>Display the selected packet in another window.</para> + </entry> + </row> + <row> + <entry><command>Resolve name</command></entry> + <entry>-</entry> + <entry>X</entry> + <entry>-</entry> + <entry>-</entry> + <entry> + <para>Cause a name resolution to be performed for the selected packet, + but NOT for every packet in the capture.</para> + </entry> + </row> + <row> + <entry><command>Go to Corresponding Packet</command></entry> + <entry>-</entry> + <entry>X</entry> + <entry>-</entry> + <entry>Go</entry> + <entry> + <para>If the selected field has a packet number in it, go to it. The + corresponding packet will often be a response which is requested by + this packet, or the request for which this packet is a response. + </para> + </entry> + </row> + <row> + <entry><command>Export Selected Packet Bytes...</command></entry> + <entry>-</entry> + <entry>X</entry> + <entry>X</entry> + <entry>File->Export</entry> + <entry> + <para>Export raw packet bytes to a binary file.</para> + </entry> + </row> + <row> + <entry><command>Protocol Preferences...</command></entry> + <entry>-</entry> + <entry>X</entry> + <entry>-</entry> + <entry>Edit</entry> + <entry> + <para>The menu item takes you to the preferences dialog and selects + the page corresponding to the protocol if there are settings + associated with the highlighted field. More information on preferences + can be found in <xref linkend="ChCustProtocolsPrefPages"/>. + </para> + </entry> + </row> + <row> + <entry><command>Collapse All</command></entry> + <entry>-</entry> + <entry>X</entry> + <entry>-</entry> + <entry>View</entry> + <entry> + <para> + Ethereal keeps a list of all the protocol subtrees that are + expanded, and uses it to ensure that the correct subtrees + are expanded when you display a packet. This menu item + collapses the tree view of all packets in the capture list. + </para> + </entry> + </row> + <row> + <entry><command>Expand All</command></entry> + <entry>-</entry> + <entry>X</entry> + <entry>-</entry> + <entry>View</entry> + <entry> + <para>Expand all subtrees in all packets in the capture. + </para> + </entry> + </row> + <row> + <entry><command>Expand Tree</command></entry> + <entry>-</entry> + <entry>X</entry> + <entry>-</entry> + <entry>View</entry> + <entry> + <para>Expand the currently selected subtree. + </para> + </entry> + </row> + </tbody> + </tgroup> + </table> + <para> + <figure id="ChWorkPacketListPanePopUpMenu"> + <title>Pop-up menu of "Packet List" pane</title> + <graphic entityref="EtherealPacketPanePopupMenu" format="PNG"/> + </figure> + <variablelist> + <varlistentry><term><command>Follow TCP Stream</command></term> + <listitem> + <para> + This menu item is the same as the Analyze menu item of + the same name. It allows you to view all the data on a TCP + stream between a pair of nodes. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Decode As...</command></term> + <listitem> + <para> + This menu item is the same as the Analyze menu item of the + same name. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Display Filters...</command></term> + <listitem> + <para> + This menu item is the same as the Analyze menu item of the same + name. It allows you to specify and manage display filters. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Mark Packet</command></term> + <listitem> + <para> + This menu item is the same as the Edit menu item of the same + name. It allows you to mark a packet. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Time Reference</command></term> + <listitem> + <para> + This menu item is the same as the Edit menu items of the same + name. It allows you to set and work with time references. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Apply as Filter</command></term> + <listitem> + <para> + This menu item is the same as the Analyze menu items of the same + name. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Prepare a Filter</command></term> + <listitem> + <para> + This menu item is the same as the Analyze menu items of the same + name. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command>Coloring Rules...</command></term> + <listitem> + <para> + This menu item is the same as the View menu item of the + same name. It allows you to colorize packets in the packet + list pane. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Print...</command></term> + <listitem> + <para> + This menu item is the same as the File menu item of the same + name. It allows you to print packets. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><command>Show Packet in New Window</command></term> + <listitem> + <para> + This menu item is the same as the View menu item of the + same name. It allows you to display the selected packet in + another window. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + <para> + <figure id="ChWorkPacketDetailsPanePopUpMenu"> + <title>Pop-up menu of "Packet Details" pane</title> + <graphic entityref="EtherealDetailsPanePopupMenu" format="PNG"/> + </figure> + <variablelist> + <varlistentry><term><command>Follow TCP Stream</command></term> + <listitem> + <para> + This menu item is the same as the Analyze menu item of the + same name. It allows you to view all the data on a TCP stream + between a pair of nodes. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Decode As...</command></term> + <listitem> + <para> + This menu item is the same as the Analyze menu item of the + same name. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Display Filters...</command></term> + <listitem> + <para> + This menu item is the same as the Analyze menu item of the same + name. It allows you to specify and manage filters. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Resolve Name</command></term> + <listitem> + <para> + This menu item causes name resolution to be performed for + the selected packet, but NOT every packet in the capture. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Go to Corresponding Packet</command></term> + <listitem> + <para> + If the selected field has a corresponding packet, go to it. + Corresponding packets will usually be a request/response packet pair + or such. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Export Selected Packet Bytes...</command></term> + <listitem> + <para> + This menu item is the same as the File menu item of the same + name. It allows you to export raw packet bytes to a binary file. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Protocol Properties...</command></term> + <listitem> + <para> + The menu item takes you to the properties dialog and selects the + page corresponding to the protocol if there are properties + associated with the highlighted field. + More information on preferences can be found in + <xref linkend="ChCustGUIPrefPage"/>. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Apply as Filter</command></term> + <listitem> + <para> + This menu item is the same as the Analyze menu items of the same + name. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Prepare a Filter</command></term> + <listitem> + <para> + This menu item is the same as the Analyze menu items of the same + name. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Collapse All</command></term> + <listitem> + <para> + Ethereal keeps a list of all the protocol subtrees that are + expanded, and uses it to ensure that the correct subtrees + are expanded when you display a packet. This menu item + collapses the tree view of all packets in the capture list. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Expand All</command></term> + <listitem> + <para> + This menu item expands all subtrees in all packets in the + capture. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Expand Tree</command></term> + <listitem> + <para> + This menu item expands the currently selected subtree. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + <para> + <figure id="ChWorkPacketBytesPanePopUpMenu"> + <title>Pop-up menu of "Packet Bytes" pane</title> + <graphic entityref="EtherealBytesPanePopupMenu" format="PNG"/> + </figure> + <variablelist> + <varlistentry><term><command>Follow TCP Stream</command></term> + <listitem> + <para> + This menu item is the same as the Analyze menu item of the + same name. It allows you to view all the data on a TCP stream + between a pair of nodes. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Decode As...</command></term> + <listitem> + <para> + This menu item is the same as the Analyze menu item of the + same name. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Display Filters...</command></term> + <listitem> + <para> + This menu item is the same as the Analyze menu item of the same + name. It allows you to specify and manage filters. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Export Selected Packet Bytes...</command></term> + <listitem> + <para> + This menu item is the same as the File menu item of the same + name. It allows you to export raw packet bytes to a binary file. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </section> + + <section id="ChWorkDisplayFilterSection"><title>Filtering packets while viewing</title> + <para> + Ethereal has two filtering languages: One used when capturing + packets, and one used when displaying packets. In this section we + explore that second type of filter: Display filters. The first one + has already been dealt with in <xref linkend="ChCapCaptureFilterSection"/>. + </para> + <para> + Display filters allow you to concentrate on the packets you are + interested in. They allow you to select packets by: + <itemizedlist> + <listitem><para>Protocol</para></listitem> + <listitem><para>The presence of a field</para></listitem> + <listitem><para>The values of fields</para></listitem> + <listitem><para>A comparison between fields</para></listitem> + <listitem><para>... and a lot more!</para></listitem> + </itemizedlist> + </para> + <para> + To select packets based on protocol type, simply type the protocol you + are interested in in the <command>Filter:</command> field in the filter + toolbar of the Ethereal window and press enter to initiate + the filter. <xref linkend="ChWorkTCPFilter"/> shows an example of what + happens when you type <command>tcp</command> in the filter field. + </para> + <note> + <title>Note!</title> + <para> + All protocol and field names are entered in lowercase. Also, don't + forget to press enter after entering the filter expression. + </para> + </note> + <figure id="ChWorkTCPFilter"><title>Filtering on the TCP protocol</title> + <graphic entityref="EtherealFilterTCP" format="JPG"/> + </figure> + <para> + As you might have noticed, only packets of the TCP protocol are displayed + now (e.g. packets 1-10 are hidden). The packet numbering will remain as + before, so the first packet shown is now packet number 11. + </para> + <note> + <title>Note!</title> + <para> + When using a display filter, all packets remain in the capture file. + The display filter only changes the display of the capture file and + not its content! + </para> + </note> + <para> + You can filter on any protocol that Ethereal understands. + You can also filter on any field that a dissector adds to the tree + view, but only if the dissector has added an abbreviation for the + field. A list of such fields is available in the Ethereal in the + <command>Add Expression...</command> dialog box. You can find more + information on the <command>Add Expression...</command> dialog box + in <xref linkend="ChWorkFilterAddExpressionSection"/>. + </para> + <para> + For example, to narrow the packet list pane down to only those + packets to or from the IP address 192.168.0.1, use + <command>ip.addr==192.168.0.1</command>. + </para> + <note> + <title>Note!</title> + <para> + To remove the filter, click on the <command>Clear</command> button + to the right of the filter field. + </para> + </note> + </section> + + <section id="ChWorkBuildDisplayFilterSection"> + <title>Building display filter expressions</title> + <para> + Ethereal provides a simple but powerful display filter language that you + can build quite complex filter expressions with. You can compare + values in packets as well as combine expressions into more + specific expressions. The following sections provide more + information on doing this. + </para> + <section> + <title>Display filter fields</title> + <para> + Every field in the packet details pane can be used as a filter + string, this will result in showing only the packets where this field + exists. For example: the + filter string: <command>tcp</command> will show all packets containing the + tcp protocol. + </para> + <para> + There is a complete list of all filter fields available + through the menu item "Help/Supported Protocols" in the page "Display Filter + Fields" of the upcoming dialog. + </para> + <para> + XXX - add some more info here and a link to the statusbar info. + </para> + </section> + <section> + <title>Comparing values</title> + <para> + You can build display filters that compare values using a number + of different comparison operators. They are shown in + <xref linkend="DispCompOps"/>. + </para> + <tip><title></title> + <para> + You can use English and C-like terms in the same way, they can even be + mixed in a filter string! + </para> + </tip> + <table id="DispCompOps"> + <title>Display Filter comparison operators</title> + <tgroup cols="3"> + <colspec colnum="1" colwidth="50pt"/> + <colspec colnum="2" colwidth="50pt"/> + <thead> + <row> + <entry>English</entry> + <entry>C-like</entry> + <entry>Description and example</entry> + </row> + </thead> + <tbody> + <row> + <entry>eq</entry> + <entry><programlisting>==</programlisting></entry> + <entry><para> + <command>Equal</command></para><para> + <programlisting>ip.addr==10.0.0.5</programlisting> + </para></entry> + </row> + <row> + <entry>ne</entry> + <entry><programlisting>!=</programlisting></entry> + <entry><para> + <command>Not equal</command></para><para> + <programlisting>ip.addr!=10.0.0.5</programlisting> + </para></entry> + </row> + <row> + <entry>gt</entry> + <entry><programlisting>></programlisting></entry> + <entry><para> + <command>Greater than</command></para><para> + <programlisting>frame.pkt_len > 10</programlisting> + </para></entry> + </row> + <row> + <entry>lt</entry> + <entry><programlisting><</programlisting></entry> + <entry><para><command>Less than</command></para><para> + <programlisting>frame.pkt_len < 128</programlisting> + </para></entry> + </row> + <row> + <entry>ge</entry> + <entry><programlisting>>=</programlisting></entry> + <entry><para> + <command>Greater than or equal to</command></para><para> + <programlisting>frame.pkt_len ge 0x100</programlisting> + </para></entry> + </row> + <row> + <entry>le</entry> + <entry><programlisting><=</programlisting></entry> + <entry><para> + <command>Less than or equal to</command></para><para> + <programlisting>frame.pkt_len <= 0x20</programlisting> + </para></entry> + </row> + </tbody> + </tgroup> + </table> + <para> + In addition, all protocol fields are typed. + <xref linkend="ChWorkFieldTypes"/> provides a list of the types and + example of how to express them. + <table id="ChWorkFieldTypes"> + <title>Display Filter Field Types</title> + <tgroup cols="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Example</entry> + </row> + </thead> + <tbody> + <row> + <entry> + Unsigned integer (8-bit, 16-bit, 24-bit, 32-bit) + </entry> + <entry><para> + You can express integers in decimal, octal, or + hexadecimal. The following display filters are + equivalent: + <programlisting> +ip.len le 1500 +ip.len le 02734 +ip.len le 0x436 + </programlisting> + </para></entry> + </row> + <row> + <entry> + Signed integer (8-bit, 16-bit, 24-bit, 32-bit) + </entry> + <entry></entry> + </row> + <row> + <entry>Boolean</entry> + <entry><para> + A boolean field is present in the protocol decode + only if its value is true. For example, + <command>tcp.flags.syn</command> is present, and + thus true, only if the SYN flag is present in a + TCP segment header.</para><para> + Thus the filter expression + <command>tcp.flags.syn</command> will select only + those packets for which this flag exists, that is, + TCP segments where the segment header contains the + SYN flag. Similarly, to find source-routed token + ring packets, use a filter expression of + <command>tr.sr</command>. + </para></entry> + </row> + <row> + <entry>Ethernet address (6 bytes)</entry> + <entry>eth.addr == ff:ff:ff:ff:ff:ff</entry> + </row> + <row> + <entry>IPv4 address</entry> + <entry>ip.addr == 192.168.0.1</entry> + </row> + <row> + <entry>IPv6 address</entry> + <entry> </entry> + </row> + <row> + <entry>IPX network number</entry> + <entry> </entry> + </row> + <row> + <entry>String (text)</entry> + <entry> </entry> + </row> + <row> + <entry> + Double-precision floating point number + </entry> + <entry> </entry> + </row> + </tbody> + </tgroup> + </table> + </para> + </section> + <section> + <title>Combining expressions</title> + <para> + You can combine filter expressions in Ethereal using the + logical operators shown in <xref linkend="FiltLogOps"/> + </para> + <table id="FiltLogOps"> + <title>Display Filter Logical Operations</title> + <tgroup cols="3"> + <colspec colnum="1" colwidth="50pt"/> + <colspec colnum="2" colwidth="50pt"/> + <thead> + <row> + <entry>English</entry> + <entry>C-like</entry> + <entry>Description and example</entry> + </row> + </thead> + <tbody> + <row> + <entry>and</entry> + <entry>&&</entry> + <entry><para> + <command>Logical AND</command></para><para> + <programlisting>ip.addr==10.0.0.5 and tcp.flags.fin</programlisting> + </para></entry> + </row> + <row> + <entry>or</entry> + <entry>||</entry> + <entry><para> + <command>Logical OR</command></para><para> + <programlisting>ip.addr==10.0.0.5 or ip.addr==192.1.1.1</programlisting> + </para></entry> + </row> + <row> + <entry>xor</entry> + <entry>^^</entry> + <entry><para> + <command>Logical XOR</command></para><para> + <programlisting>tr.dst[0:3] == 0.6.29 xor tr.src[0:3] == 0.6.29</programlisting> + </para></entry> + </row> + <row> + <entry>not</entry> + <entry>!</entry> + <entry><para> + <command>Logical NOT</command></para><para> + <programlisting>not llc</programlisting> + </para></entry> + </row> + <row> + <entry>[...]</entry> + <entry></entry> + <entry><para> + <command>Substring Operator</command></para><para> + Ethereal allows you to select subsequences of a + sequence in rather elaborate ways. After a label you + can place a pair of brackes [] containing a comma + separated list of range specifiers. </para><para> + <programlisting>eth.src[0:3] == 00:00:83</programlisting></para><para> + The example above uses the n:m format to specify a + single range. In this case n is the beginning offset + and m is the length of the range + being specified.</para><para> + <programlisting> +eth.src[1-2] == 00:83 + </programlisting></para><para> + The example above uses the n-m format to specify a + single range. In this case n is the beginning offset + and m is the ending offset. </para><para> + <programlisting>eth.src[:4] == 00:00:83:00</programlisting></para><para> + The example above uses the :m format, which takes + everything from the beginning of a sequence to offset m. + It is equivalent to 0:m</para><para> + <programlisting>eth.src[4:] == 20:20</programlisting></para><para> + The example above uses the n: format, which takes + everything from offset n to the end of the + sequence. </para><para> + <programlisting>eth.src[2] == 83</programlisting></para><para> + The example above uses the n format to specify a + single range. In this case the element in the + sequence at offset n is selected. This is equivalent + to n:1.</para><para> + <programlisting>eth.src[0:3,1-2,:4,4:,2] == +00:00:83:00:83:00:00:83:00:20:20:83</programlisting></para><para> + Ethereal allows you to string together single ranges + in a comma separated list to form compound ranges as + shown above. + </para></entry> + </row> + </tbody> + </tgroup> + </table> + </section> + <section><title>A common mistake</title> + <para> + Often people use a filter string to display something like + <command>ip.addr == 1.2.3.4</command> which will display all packets + containing the IP address 1.2.3.4. + </para> + <para> + Then they use <command>ip.addr != 1.2.3.4</command> to see all packets + not containing the IP address 1.2.3.4 in it. Unfortunately, this does + <command>not</command> do the expected. + </para> + <para> + Instead, that expression will even be true for packets where either + source or destination IP address equals 1.2.3.4. The reason for this, + is that the expression <command>ip.addr != 1.2.3.4</command> must be read as "the + packet contains a field named ip.addr with a value + different from 1.2.3.4". As an IP datagram contains both a source and + a destination address, the expression will evaluate to true whenever + at least one of the two addresses differs from 1.2.3.4. + </para> + <para> + If you want to + filter out all packets containing IP datagrams to or from IP address + 1.2.3.4, then the correct filter is <command>!(ip.addr == 1.2.3.4)</command> as it + reads "show me all the packets for which it is not true + that a field named ip.addr exists with a value of 1.2.3.4", or in + other words, "filter out all packets for which there are + no occurrences of a field named ip.addr with the value 1.2.3.4". + </para> + </section> + </section> + + <section id="ChWorkFilterAddExpressionSection"> + <title>The "Filter Expression" dialog box</title> + <para> + When you are accustomed to Ethereal's filtering system and know what + labels you wish to use in your filters it can be very quick to + simply type a filter string. However if you are new to Ethereal or + are working with a slightly unfamiliar protocol it can be very + confusing to try to figure out what to type. The Filter Expression + dialog box helps with this. + </para> + <tip><title>Tip!</title> + <para> + The "Filter Expression" dialog box is an excellent way to learn how to + write Ethereal display filter strings. + </para> + </tip> + <figure id="ChWorkFilterAddExpression1"> + <title>The "Filter Expression" dialog box</title> + <graphic entityref="EtherealFilterAddExpression" format="PNG"/> + </figure> + <para> + When you first bring up the Filter Expression dialog box you are shown a + tree list of field names, organized by protocol, and a box for + selecting a relation. + </para> + <variablelist> + <varlistentry><term><command>Field Name</command></term> + <listitem> + <para> + Select a protocol field from the protocol field tree. + Every protocol with filterable fields is listed at the + top level. By clicking on the "+" next to a protocol name + you can get a list of the field names available for filtering + for that protocol. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Relation</command></term> + <listitem> + <para> + Select a relation from the list of available relation. + The <command>is present</command> is a unary relation which + is true if the selected field is present in a packet. All + other listed relations are binary relations which require additional + data (e.g. a <command>Value</command> to match) to complete. + </para> + </listitem> + </varlistentry> + </variablelist> + <para> + When you select a field from the field name list and select a + binary relation (such as the equality relation ==) you will be + given the opportunity to enter a value, and possibly some range + information. + </para> + <variablelist> + <varlistentry><term><command>Value</command></term> + <listitem> + <para> + You may enter an appropriate value in the + <command>Value</command> text box. The <command>Value</command> + will also indicate the type of value for the + <command>field name</command> you have selected ( like + character string ). + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Predefined values</command></term> + <listitem> + <para> + Some of the protocol fields have predefined values available, much like + enum's in C. If the selected protocol field has such values defined, you + can choose it here. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Range</command></term> + <listitem> + <para> + XXX - add an explanation here! + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>OK</command></term> + <listitem> + <para> + When you have built a satisfactory expression click + <command>OK</command> and a filter string will be + built for you. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Cancel</command></term> + <listitem> + <para> + You can leave the <command>Add Expression...</command> dialog + box without any effect by clicking the <command>Cancel</command> + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + + <section id="ChWorkDefineFilterSection"><title>Defining and saving filters</title> + <para> + You can define filters with Ethereal and give them labels for + later use. This can save time in remembering and retyping some of + the more complex filters you use. + </para> + <para> + To define a new filter or edit an existing filter, select the + <command>Capture Filters...</command> menu item from the Capture menu + or the <command>Display Filters...</command> menu item from the Analyze + menu. Ethereal will then pop up the Filters dialog as shown in + <xref linkend="FiltersDialog"/>. + </para> + <note> + <title>Note!</title> + <para> + The mechanisms for defining and saving capture filters and display + filters are almost identical. So both will be described here, + differences between these two will be marked as such. + </para> + </note> + <warning><title>Warning!</title> + <para> + You must use <command>Save</command> to save your filters permanently. + <command>Ok</command> or <command>Apply</command> will not save the filters, + so they will be lost when you close Ethereal. + </para> + </warning> + <figure id="FiltersDialog"> + <title>The "Capture Filters" and "Display Filters" dialog boxes</title> + <graphic entityref="EtherealFilters" format="PNG"/> + </figure> + <para> + <variablelist> + <varlistentry><term><command>New</command></term> + <listitem> + <para> + This button adds a new filter to the list of filters. The currently + entered values from Filter name and Filter string will be used. If + any of these fields are empty, it will be set to "new". + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Delete</command></term> + <listitem> + <para> + This button deletes the selected filter. It will be greyed out, if no + filter is selected. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Filter</command></term> + <listitem> + <para> + You can select a filter from this list (which will fill in the + filter name and filter string in the fields down the bottom of the + dialog box). + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Filter name:</command></term> + <listitem> + <para> + You can change the name of the currently selected filter here. + </para> + <note><title>Note!</title> + <para> + The filter name will only be used in this dialog to identify the + filter for your convenience, it will not be used elsewhere. You can + add multiple filters with the same name, but this is not very useful. + </para> + </note> + </listitem> + </varlistentry> + <varlistentry><term><command>Filter string:</command></term> + <listitem> + <para> + You can change the filter string of the currently selected filter here. + Display Filter only: the string will be syntax checked while you are + typing. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Add Expression...</command></term> + <listitem> + <para> + Display Filter only: This button brings up the Add Expression + dialog box which assists in building filter strings. You can find + more information about the Add Expression dialog in + <xref linkend="ChWorkFilterAddExpressionSection"/> + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>OK</command></term> + <listitem> + <para> + Display Filter only: This button applies the selected filter to the + current display and closes the dialog. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Apply</command></term> + <listitem> + <para> + Display Filter only: This button applies the selected filter to the + current display, and keeps the dialog open. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Save</command></term> + <listitem> + <para> + Save the current settings in this dialog. The file location and + format is explained in <xref linkend="AppFiles"/>. + </para> + </listitem> + </varlistentry> + <varlistentry><term><command>Close</command></term> + <listitem> + <para> + Close this dialog. This will discard unsaved settings. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </section> + + <section id="ChWorkFindPacketSection"><title>Finding packets</title> + <para> + You can easily find packets once you have captured some packets or + have read in a previously saved capture file. Simply select the + <command>Find Packet...</command> menu item from the + <command>Edit</command> menu. Ethereal will pop up the dialog box + shown in <xref linkend="ChWorkFindPacketDialog"/>. + </para> + <section><title>The "Find Packet" dialog box</title> + <figure id="ChWorkFindPacketDialog"> + <title>The "Find Packet" dialog box</title> + <graphic entityref="EtherealFindPacket" format="PNG"/> + </figure> + <para> + You might first select the kind of thing to search for: + <itemizedlist> + <listitem> + <para> + <command>Display filter</command> + </para> + <para> + Simply enter a display filter string into the + <command>Filter:</command> field, select a direction, and click on OK. + </para> + <para> + For example, to find the three way handshake for a connection from + host 192.168.0.1, use the following filter string: + <programlisting>ip.addr==192.168.0.1 and tcp.flags.syn</programlisting> + For more details on display filters, see <xref linkend="ChWorkDisplayFilterSection"/> + </para> + </listitem> + <listitem> + <para> + <command>Hex Value</command> + </para> + <para> + Search for a specific byte sequence in the packet data. + </para> + <para> + For example, use "00:00" to find the next packet including two + null bytes in the packet data. + </para> + </listitem> + <listitem> + <para> + <command>String</command> + </para> + <para> + Find a string in the packet data, with various options. + </para> + </listitem> + </itemizedlist> + </para> + <para> + The value to be found will by syntax checked while you type it in. If the + syntax check of your value succeeded, the background of the entry field + will turn green, if it fails, it will turn red. + </para> + <para> + You can choose the direction to be searched for: + <itemizedlist> + <listitem> + <para><command>Up</command></para> + <para>Search upwards in the packet list (decreasing packet numbers).</para> + </listitem> + </itemizedlist> + <itemizedlist> + <listitem> + <para><command>Down</command></para> + <para>Search downwards in the packet list (increasing packet numbers).</para> + </listitem> + </itemizedlist> + </para> + </section> + <section><title>The "Find Next" command</title> + <para> + "Find Next" will continue searching with the same options like in the last + "Find Packet" run. + </para> + </section> + <section><title>The "Find Previous" command</title> + <para> + "Find Previous" will do the same thing as "Find Next", but with reverse + search direction. + </para> + </section> + </section> + + <section id="ChWorkGoToPacketSection"><title>Go to a specific packet</title> + <para> + You can easily jump to specific packets with one of the menu items in the + Go menu. + </para> + <section><title>The "Go to Packet" dialog box</title> + <figure id="ChWorkGoToPacketDialog"> + <title>The "Go To Packet" dialog box</title> + <graphic entityref="EtherealGoToPacket" format="PNG"/> + </figure> + <para> + This dialog box will let you enter a packet number. When you press + <command>OK</command>, Ethereal will jump to that packet. + </para> + </section> + <section><title>The "Go to Corresponding Packet" command</title> + <para> + If a protocol field is selected, which points to another packet in the + capture file, this command will jump to that packet. + </para> + <note><title>Note!</title> + <para> + As these protocol fields now work like links (just as in your + Web browser), it's easier simply to double-click on the field to jump + to the corresponding field. + </para> + </note> + </section> + <section><title>The "Go to First Packet" command</title> + <para> + This command will simply jump to the first packet displayed. + </para> + </section> + <section><title>The "Go to Last Packet" command</title> + <para> + This command will simply jump to the last packet displayed. + </para> + </section> + </section> + + <section id="ChWorkMarkPacketSection"><title>Marking packets</title> + <para> + You can mark packets in the "Packet List" pane. A marked packet will + be shown with black background, regardless of the coloring rules set. + Marking a packet can be useful to find it later while analyzing in a large + capture file. + </para> + <warning><title>Warning!</title> + <para> + The packet marks are not stored in the capture file or anywhere else, + so all packet marks will be lost if you close the capture file. + </para> + </warning> + <para> + You can use packet marking to control the output of packets when + saving/exporting/printing. To do so, an option in the packet range is + available, see <xref linkend="ChIOPacketRangeSection"/>. + </para> + <para> + There are three functions to manipulate the marked state of a packet: + <itemizedlist> + <listitem> + <para> + <command>Mark packet</command> toggle the marked state of a single packet. + </para> + </listitem> + <listitem> + <para> + <command>Mark all packets</command> set the mark state of all packets. + </para> + </listitem> + <listitem> + <para> + <command>Unmark all packets</command> reset the mark state of all packets. + </para> + </listitem> + </itemizedlist> + These mark function are available from the "Edit" menu, and the "Mark packet" + function is also available from the popup menu of the "Packet List" pane. + </para> + </section> + + <section id="ChWorkTimeFormatsSection"><title>Time display formats and time + references</title> + <para> + While packets are captured, each packet is timestamped. These timestamps + will be saved to the capture file, so they will be available for later + analysis. + </para> + <para> + When the packets are displayed, the presentation of these timestamps can + be chosen by the user. There are four presentation formats available: + <itemizedlist> + <listitem><para><command>Time of Day</command>, e.g. 20:02:48.863096 + The absolute time of the day when the packet was captured.</para> + </listitem> + <listitem><para><command>Date and Time of Day</command>, e.g. 2004-06-22 20:02:48.863096 + The absolute date and time of the day when the packet was captured.</para> + </listitem> + <listitem><para><command>Seconds Since Beginning of Capture</command>, e.g. 123.299139 + The time relative to the start of the capture file or the first + "Time Reference" before this packet (see <xref + linkend="ChWorkTimeReferencePacketSection"/>).</para> + </listitem> + <listitem><para><command>Seconds Since Previous Packet</command>, e.g. 1.162423 + The time relative to the previous packet.</para> + </listitem> + </itemizedlist> + The time format can be selected from the View menu, see + <xref linkend="ChUseEtherealViewMenu"/>. + </para> + <para> + XXX - how is the GMT / localtime thing handled. + </para> + <section id="ChWorkTimeReferencePacketSection"> + <title>Packet time referencing</title> + <para> + The user can set time references to packets. A time reference is the + starting point for all subsequent packet time calculations. It will be + useful, if you want to see the time values relative to a special packet, + e.g. the start of a new request. It's possible to set multiple time + references in the capture file. + </para> + <warning><title>Warning!</title> + <para> + The time references will not be saved permanently and will be lost when + you close the capture file. + </para> + </warning> + <note><title>Note!</title> + <para> + Time referencing will only be useful, if the time display format is set to + "Seconds Since Beginning of Capture". If one of the other time display + formats are used, time referencing will have no effect (and will make no + sense either). + </para> + </note> + <para> + To work with time references, choose one of the "Time Reference" items + in the "Edit" menu , see <xref linkend="ChUseEditMenuSection"/>, or from + the popup menu of the "Packet List" pane. + </para> + <itemizedlist> + <listitem><para><command>Set Time Reference (toggle)</command> + Toggles the time reference state of the currently selected + packet to on or off.</para> + </listitem> + <listitem><para><command>Find Next</command> + Find the next time referenced packet in the "Packet List" pane. + </para> + </listitem> + <listitem><para><command>Find Previous</command> + Find the previous time referenced packet in the "Packet List" + pane. + </para> + </listitem> + </itemizedlist> + <para> + <figure id="ChWorkTimeReference"> + <title>Ethereal showing a time referenced packet</title> + <graphic entityref="EtherealTimeReference" format="PNG"/> + </figure> + </para> + <para> + A time referenced packet will be marked with the string *REF* in the Time + column (see packet number 10). All subsequent packets will show the time + since the last time reference. + </para> + </section> + </section> + +</chapter> +<!-- End of EUG Chapter Work --> + diff --git a/docbook/ug-src/EUG_meta_info.xml b/docbook/ug-src/EUG_meta_info.xml index 079e638b66..309ae26a38 100644 --- a/docbook/ug-src/EUG_meta_info.xml +++ b/docbook/ug-src/EUG_meta_info.xml @@ -1,36 +1,38 @@ -<bookinfo>
- <title>&DocumentTitle;</title>
- <subtitle>&DocumentSubTitle;</subtitle>
- <authorgroup>
- <author>
- <firstname>&AuthorFirstName;</firstname>
- <surname>&AuthorSurname;</surname>
- <affiliation><orgname>&AuthorOrgName;</orgname></affiliation>
- </author>
- <author>
- <firstname>&AuthorFirstName2;</firstname>
- <surname>&AuthorSurname2;</surname>
- <affiliation><orgname>&AuthorOrgName2;</orgname></affiliation>
- </author>
- <author>
- <firstname>&AuthorFirstName3;</firstname>
- <surname>&AuthorSurname3;</surname>
- <affiliation><orgname>&AuthorOrgName3;</orgname></affiliation>
- </author>
- </authorgroup>
- <!-- <edition>&DocumentEdition;</edition>
- <pubdate>&DocumentPubDate;</pubdate> -->
- <copyright>
- <year>&DocumentCopyrightYear;</year>
- <holder>&DocumentCopyrightHolder1;</holder>
- <holder>&DocumentCopyrightHolder2;</holder>
- <holder>&DocumentCopyrightHolder3;</holder>
- </copyright>
-
- <graphic scale="100" entityref="EtherealLogo" format="PNG"/>
-
- <legalnotice>
- &DocumentLegalNotice;
- </legalnotice>
-
-</bookinfo>
+<!-- $Id$ --> + +<bookinfo> + <title>&DocumentTitle;</title> + <subtitle>&DocumentSubTitle;</subtitle> + <authorgroup> + <author> + <firstname>&AuthorFirstName;</firstname> + <surname>&AuthorSurname;</surname> + <affiliation><orgname>&AuthorOrgName;</orgname></affiliation> + </author> + <author> + <firstname>&AuthorFirstName2;</firstname> + <surname>&AuthorSurname2;</surname> + <affiliation><orgname>&AuthorOrgName2;</orgname></affiliation> + </author> + <author> + <firstname>&AuthorFirstName3;</firstname> + <surname>&AuthorSurname3;</surname> + <affiliation><orgname>&AuthorOrgName3;</orgname></affiliation> + </author> + </authorgroup> + <!-- <edition>&DocumentEdition;</edition> + <pubdate>&DocumentPubDate;</pubdate> --> + <copyright> + <year>&DocumentCopyrightYear;</year> + <holder>&DocumentCopyrightHolder1;</holder> + <holder>&DocumentCopyrightHolder2;</holder> + <holder>&DocumentCopyrightHolder3;</holder> + </copyright> + + <graphic scale="100" entityref="EtherealLogo" format="PNG"/> + + <legalnotice> + &DocumentLegalNotice; + </legalnotice> + +</bookinfo> diff --git a/docbook/ug-src/EUG_preface.xml b/docbook/ug-src/EUG_preface.xml index 6bc1613f46..a03bba8bc2 100644 --- a/docbook/ug-src/EUG_preface.xml +++ b/docbook/ug-src/EUG_preface.xml @@ -1,183 +1,185 @@ -<preface id="Preface">
- <title>Preface</title>
- <section id="PreForeword">
- <title>Foreword</title>
- <para>
- Ethereal is one of those programs that many network managers would love
- to be able to use, but they are often prevented from getting what they
- would like from Ethereal because of the lack of documentation.
- </para>
- <para>
- This document is part of an effort by the Ethereal team to improve the
- usability of Ethereal.
- </para>
- <para>
- We hope that you find it useful, and look forward to your comments.
- </para>
- </section>
-
- <section id="PreAudience">
- <title>Who should read this document?</title>
- <para>
- The intended audience of this book is anyone using Ethereal.
- </para>
- <para>
- This book will explain all the basics and also some of the advanced features
- that Ethereal provides. As Ethereal has become a very complex program since
- the early days, not every feature of Ethereal might be explained in this
- book.
- </para>
- <para>
- This book is not intended to explain network sniffing in general and it will
- not provide details about specific network protocols. However, as this book
- evolves in time (like Ethereal itself), this might change in the future.
- </para>
- <para>
- By reading this book, you will learn how to install Ethereal, how to use the
- basic elements of the graphical user interface (like the menu) and what's
- behind some of the advanced features that are maybe not that obvious at first
- sight. It will
- hopefully guide you around some common problems that frequently appears for
- new (and sometimes even advanced) users of Ethereal.
- </para>
- </section>
-
- <section id="PreAck">
- <title>Acknowledgements</title>
- <para>
- The authors would like to thank the whole Ethereal team for their
- assistance. In particular, the authors would like to thank:
- <itemizedlist>
- <listitem>
- <para>
- Gerald Combs, for initiating the Ethereal project and funding to
- do this documentation.
- </para>
- </listitem>
- <listitem>
- <para>
- Guy Harris, for many helpful hints and a great deal of patience
- in reviewing this document.
- </para>
- </listitem>
- <listitem>
- <para>
- Gilbert Ramirez, for general encouragement and helpful hints along
- the way.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- The authors would also like to thank the following people for their
- helpful feedback on this document:
- <itemizedlist>
- <listitem>
- <para>
- Pat Eyler, for his suggestions on improving the example on
- generating a backtrace.
- </para>
- </listitem>
- <listitem>
- <para>
- Martin Regner, for his various suggestions and corrections.
- </para>
- </listitem>
- <listitem>
- <para>
- Graeme Hewson, for a lot of grammatical corrections.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- The authors would like to acknowledge those man page and README authors
- for the ethereal project from who sections of this document borrow heavily:
- <itemizedlist>
- <listitem>
- <para>
- Scott Renfro from whose <command>mergecap</command> man page
- <xref linkend="AppToolsmergecap"/> is derived.
- </para>
- </listitem>
- <listitem>
- <para>
- Ashok Narayanan from whose <command>text2pcap</command> man page
- <xref linkend="AppToolstext2pcap"/> is derived.
- </para>
- </listitem>
- <listitem>
- <para>
- Frank Singleton from whose <filename>README.idl2eth</filename>
- <xref linkend="AppToolsidl2eth"/> is derived.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </section>
-
- <section id="PreAbout">
- <title>About this document</title>
- <para>
- This book was originally developed by
- <ulink url="mailto:&AuthorEmail;">Richard Sharpe</ulink> with
- funds provided from the Ethereal Fund. It was updated by
- <ulink url="mailto:&AuthorEmail2;">Ed Warnicke</ulink> and more recently
- redesigned and updated by <ulink url="mailto:&AuthorEmail3;">Ulf
- Lamping</ulink>.
- </para>
- <para>
- It is written in DocBook/XML.
- </para>
- <para>
- You will find some specially marked parts in this book:
- </para>
- <warning><title>This is a warning!</title>
- <para>
- You should pay attention to a warning, as otherwise data loss might occur.
- </para>
- </warning>
- <note><title>This is a note!</title>
- <para>
- A note will point you to common mistakes and things that might not be
- obvious.
- </para>
- </note>
- <tip><title>This is a tip!</title>
- <para>
- Tips will be helpful for your everyday work using Ethereal.
- </para>
- </tip>
- </section>
-
- <section id="PreDownload">
- <title>Where to get the latest copy of this document?</title>
- <para>
- The latest copy of this documentation can always be found at:
- <!-- <ulink url="&LatestVersionWebsite;">&LatestVersionWebsite;</ulink>;
- and at: -->
- <ulink url="&EtherealWebSite;">
- &EtherealWebSite;/docs/user-guide/
- </ulink>.
- </para>
- <!-- <para>
- In addition, you can find a PDF version of the guide at:
- <ulink url="&LatestVersionPDFWebsiteA4;">
- &LatestVersionPDFWebsiteA4;
- </ulink>
- in A4 and
- <ulink url="&LatestVersionPDFWebsiteUSLetter;">
- &LatestVersionPDFWebsiteUSLetter
- </ulink>
- in US Letter.
- </para> -->
- </section>
-
- <section id="PreFeedback">
- <title>Providing feedback about this document</title>
- <para>
- Should you have any feedback about this document, please send them
- to the authors through <ulink url="mailto:&EtherealDevMailList;">&EtherealDevMailList;</ulink>.
- </para>
- </section>
-</preface>
+<!-- $Id$ --> + +<preface id="Preface"> + <title>Preface</title> + <section id="PreForeword"> + <title>Foreword</title> + <para> + Ethereal is one of those programs that many network managers would love + to be able to use, but they are often prevented from getting what they + would like from Ethereal because of the lack of documentation. + </para> + <para> + This document is part of an effort by the Ethereal team to improve the + usability of Ethereal. + </para> + <para> + We hope that you find it useful, and look forward to your comments. + </para> + </section> + + <section id="PreAudience"> + <title>Who should read this document?</title> + <para> + The intended audience of this book is anyone using Ethereal. + </para> + <para> + This book will explain all the basics and also some of the advanced features + that Ethereal provides. As Ethereal has become a very complex program since + the early days, not every feature of Ethereal might be explained in this + book. + </para> + <para> + This book is not intended to explain network sniffing in general and it will + not provide details about specific network protocols. However, as this book + evolves in time (like Ethereal itself), this might change in the future. + </para> + <para> + By reading this book, you will learn how to install Ethereal, how to use the + basic elements of the graphical user interface (like the menu) and what's + behind some of the advanced features that are maybe not that obvious at first + sight. It will + hopefully guide you around some common problems that frequently appears for + new (and sometimes even advanced) users of Ethereal. + </para> + </section> + + <section id="PreAck"> + <title>Acknowledgements</title> + <para> + The authors would like to thank the whole Ethereal team for their + assistance. In particular, the authors would like to thank: + <itemizedlist> + <listitem> + <para> + Gerald Combs, for initiating the Ethereal project and funding to + do this documentation. + </para> + </listitem> + <listitem> + <para> + Guy Harris, for many helpful hints and a great deal of patience + in reviewing this document. + </para> + </listitem> + <listitem> + <para> + Gilbert Ramirez, for general encouragement and helpful hints along + the way. + </para> + </listitem> + </itemizedlist> + </para> + <para> + The authors would also like to thank the following people for their + helpful feedback on this document: + <itemizedlist> + <listitem> + <para> + Pat Eyler, for his suggestions on improving the example on + generating a backtrace. + </para> + </listitem> + <listitem> + <para> + Martin Regner, for his various suggestions and corrections. + </para> + </listitem> + <listitem> + <para> + Graeme Hewson, for a lot of grammatical corrections. + </para> + </listitem> + </itemizedlist> + </para> + <para> + The authors would like to acknowledge those man page and README authors + for the ethereal project from who sections of this document borrow heavily: + <itemizedlist> + <listitem> + <para> + Scott Renfro from whose <command>mergecap</command> man page + <xref linkend="AppToolsmergecap"/> is derived. + </para> + </listitem> + <listitem> + <para> + Ashok Narayanan from whose <command>text2pcap</command> man page + <xref linkend="AppToolstext2pcap"/> is derived. + </para> + </listitem> + <listitem> + <para> + Frank Singleton from whose <filename>README.idl2eth</filename> + <xref linkend="AppToolsidl2eth"/> is derived. + </para> + </listitem> + </itemizedlist> + </para> + </section> + + <section id="PreAbout"> + <title>About this document</title> + <para> + This book was originally developed by + <ulink url="mailto:&AuthorEmail;">Richard Sharpe</ulink> with + funds provided from the Ethereal Fund. It was updated by + <ulink url="mailto:&AuthorEmail2;">Ed Warnicke</ulink> and more recently + redesigned and updated by <ulink url="mailto:&AuthorEmail3;">Ulf + Lamping</ulink>. + </para> + <para> + It is written in DocBook/XML. + </para> + <para> + You will find some specially marked parts in this book: + </para> + <warning><title>This is a warning!</title> + <para> + You should pay attention to a warning, as otherwise data loss might occur. + </para> + </warning> + <note><title>This is a note!</title> + <para> + A note will point you to common mistakes and things that might not be + obvious. + </para> + </note> + <tip><title>This is a tip!</title> + <para> + Tips will be helpful for your everyday work using Ethereal. + </para> + </tip> + </section> + + <section id="PreDownload"> + <title>Where to get the latest copy of this document?</title> + <para> + The latest copy of this documentation can always be found at: + <!-- <ulink url="&LatestVersionWebsite;">&LatestVersionWebsite;</ulink>; + and at: --> + <ulink url="&EtherealWebSite;"> + &EtherealWebSite;/docs/user-guide/ + </ulink>. + </para> + <!-- <para> + In addition, you can find a PDF version of the guide at: + <ulink url="&LatestVersionPDFWebsiteA4;"> + &LatestVersionPDFWebsiteA4; + </ulink> + in A4 and + <ulink url="&LatestVersionPDFWebsiteUSLetter;"> + &LatestVersionPDFWebsiteUSLetter + </ulink> + in US Letter. + </para> --> + </section> + + <section id="PreFeedback"> + <title>Providing feedback about this document</title> + <para> + Should you have any feedback about this document, please send them + to the authors through <ulink url="mailto:&EtherealDevMailList;">&EtherealDevMailList;</ulink>. + </para> + </section> +</preface> diff --git a/docbook/user-guide.xml b/docbook/user-guide.xml index 7f25cb9fde..a1c78958b7 100644 --- a/docbook/user-guide.xml +++ b/docbook/user-guide.xml @@ -1,285 +1,287 @@ -<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
-
-<!--
-BIOGRAPHICAL SECTION
--Use this section to encode all biographical information
--->
-
-<!-- Author's Names -->
- <!ENTITY AuthorFullName "Richard Sharpe">
- <!ENTITY AuthorFirstName "Richard">
- <!ENTITY AuthorOtherName "">
- <!ENTITY AuthorSurname "Sharpe">
-
- <!ENTITY AuthorFullName2 "Ed Warnicke">
- <!ENTITY AuthorFirstName2 "Ed">
- <!ENTITY AuthorOtherName2 "">
- <!ENTITY AuthorSurname2 "Warnicke">
-
- <!ENTITY AuthorFullName3 "Ulf Lamping">
- <!ENTITY AuthorFirstName3 "Ulf">
- <!ENTITY AuthorOtherName3 "">
- <!ENTITY AuthorSurname3 "Lamping">
-
-<!--Author's Affiliation -->
- <!ENTITY AuthorShortAffiliation "">
- <!ENTITY AuthorJobTitle "Director">
- <!ENTITY AuthorOrgName "NS Computer Software and Services P/L">
- <!ENTITY AuthorOrgDiv "">
- <!ENTITY AuthorEmail "rsharpe[AT]ns.aus.com">
-
- <!ENTITY AuthorShortAffiliation2 "">
- <!ENTITY AuthorJobTitle2 "">
- <!ENTITY AuthorOrgName2 "">
- <!ENTITY AuthorOrgDiv2 "">
- <!ENTITY AuthorEmail2 "hagbard[AT]physics.rutgers.edu">
-
- <!ENTITY AuthorShortAffiliation3 "">
- <!ENTITY AuthorJobTitle3 "">
- <!ENTITY AuthorOrgName3 "">
- <!ENTITY AuthorOrgDiv3 "">
- <!ENTITY AuthorEmail3 "ulf.lamping[AT]web.de">
-
-
-
-
-<!--
-DOCUMENT SECTION
--Use this section to encode all document information
--->
-
- <!ENTITY DocumentTitle "<application>Ethereal</application> User's Guide">
- <!ENTITY DocumentSubTitle "&DocumentVersion; for Ethereal &EtherealCurrentVersion;">
- <!ENTITY DocumentTitleAbbreviation "EUG">
-
- <!ENTITY DocumentCopyrightHolder1 "Richard Sharpe">
- <!ENTITY DocumentCopyrightHolder2 "Ed Warnicke">
- <!ENTITY DocumentCopyrightHolder3 "Ulf Lamping">
- <!ENTITY DocumentCopyrightYear "2004">
-
- <!ENTITY DocumentEdition "Third ">
- <!ENTITY DocumentVersion "V2.00">
- <!ENTITY DocumentPubDate "2004">
-
-<!ENTITY DocumentLegalNotice "<para>Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts.</para><para>All logos and trademarks in this document are property of their respective owner.</para>">
-
-<!--
-Ethereal Info
--->
- <!ENTITY EtherealCurrentVersion "0.10.5">
- <!ENTITY EtherealNextMinorVersion "0.10.6">
- <!ENTITY EtherealWebSite "http://www.ethereal.com">
- <!ENTITY EtherealDownloadPage "&EtherealWebSite;/download.html">
- <!ENTITY EtherealBinariesPage "&EtherealWebSite;/download.html#binaries">
- <!ENTITY EtherealAuthorsPage "&EtherealWebSite;/introduction.html#authors">
- <!ENTITY EtherealProtocolsPage "&EtherealWebSite;/docs/dfref/">
- <!ENTITY EtherealFAQPage "&EtherealWebSite;/faq.html">
- <!ENTITY EtherealFAQPromiscPage "&EtherealWebSite;/faq#promiscsniff">
- <!ENTITY EtherealMediaPage "&EtherealWebSite;/media.html">
- <!ENTITY EtherealCurrentVersionTarFile "0.10.5">
-
- <!ENTITY EtherealDevMailList "ethereal-dev[AT]ethereal.com">
- <!ENTITY EtherealUsersMailList "ethereal-users[AT]ethereal.com">
-
-
-<!--
-Winpcap Info
--->
- <!ENTITY WinPcapWebsite "http://winpcap.polito.it">
- <!ENTITY WinPcapDownloadWebsite "http://winpcap.polito.it/install/Default.htm">
-
-<!--
-Gnu info
--->
- <!ENTITY GPLWebsite "http://www.gnu.org/copyleft/gpl.html">
-
-<!-- Self referential info
--->
-
- <!ENTITY LatestVersionWebsite "http://www.richardsharpe.com/richard/ethereal/user-guide/book1.html" >
- <!ENTITY LatestVersionPDFWebsiteA4 "http://www.richardsharpe.com/richard/ethereal/user-guide/user-guide-a4.pdf" >
- <!ENTITY LatestVersionPDFWebsiteUSLetter "http://www.richardsharpe.com/richard/ethereal/user-guide/user-guide-usletter.pdf" >
-<!--
-FILE SECTION
--Use this section to specify the files that make up the book. Use FPI (public identifiers)
--->
-<!-- These refer to graphics files and figures contained in the document -->
- <!-- -->
- <!ENTITY EtherealLogo SYSTEM "./graphics/ethereal-logo.png" NDATA PNG>
-
- <!-- 1st Chapter -->
- <!ENTITY EtherealMain1 SYSTEM "./graphics/ethereal-main.png" NDATA PNG>
-
- <!-- 2nd Chapter -->
-
- <!-- Third Chapter -->
- <!ENTITY EtherealEmpty SYSTEM "./graphics/ethereal-empty.png" NDATA PNG>
- <!ENTITY EtherealThreePane1 SYSTEM "./graphics/ethereal-3pane.png" NDATA PNG>
- <!ENTITY EtherealMenuOnly SYSTEM "./graphics/ethereal-menu.png" NDATA PNG>
- <!ENTITY EtherealMainToolbar SYSTEM "./graphics/ethereal-main-toolbar.png" NDATA PNG>
- <!ENTITY EtherealFilterToolbar SYSTEM "./graphics/ethereal-filter-toolbar.png" NDATA PNG>
- <!ENTITY EtherealListPane SYSTEM "./graphics/ethereal-list-pane.png" NDATA PNG>
- <!ENTITY EtherealDetailsPane SYSTEM "./graphics/ethereal-details-pane.png" NDATA PNG>
- <!ENTITY EtherealBytesPane SYSTEM "./graphics/ethereal-bytes-pane.png" NDATA PNG>
- <!ENTITY EtherealBytesPaneTabs SYSTEM "./graphics/ethereal-bytes-pane-tabs.png" NDATA PNG>
- <!ENTITY EtherealStatusbarEmpty SYSTEM "./graphics/ethereal-statusbar-empty.png" NDATA PNG>
- <!ENTITY EtherealStatusbarLoaded SYSTEM "./graphics/ethereal-statusbar-loaded.png" NDATA PNG>
- <!ENTITY EtherealStatusbarSelected SYSTEM "./graphics/ethereal-statusbar-selected.png" NDATA PNG>
- <!ENTITY EtherealSaveAs SYSTEM "./graphics/ethereal-save-as.png" NDATA PNG>
- <!ENTITY EtherealOpen SYSTEM "./graphics/ethereal-open.png" NDATA PNG>
- <!ENTITY EtherealPacketSelected1 SYSTEM "./graphics/ethereal-packet-selected.png" NDATA PNG>
- <!ENTITY EtherealPacketSepView SYSTEM "./graphics/ethereal-packet-sep-win.png" NDATA PNG>
- <!ENTITY EtherealFilterTCP SYSTEM "./graphics/ethereal-display-filter-tcp.png" NDATA PNG>
- <!ENTITY EtherealColoringRulesDialog SYSTEM "./graphics/ethereal-coloring-rules-dialog.png" NDATA PNG>
- <!ENTITY EtherealEditColorDialog SYSTEM "./graphics/ethereal-edit-color-rule-dialog.png" NDATA PNG>
- <!ENTITY EtherealChooseColorDialog SYSTEM "./graphics/ethereal-choose-color-rule.png" NDATA PNG>
- <!ENTITY EtherealFollowStream SYSTEM "./graphics/ethereal-follow-stream.png" NDATA PNG>
- <!ENTITY EtherealFindPacket SYSTEM "./graphics/ethereal-find-packet.png" NDATA PNG>
- <!ENTITY EtherealGoToPacket SYSTEM "./graphics/ethereal-goto-packet.png" NDATA PNG>
- <!ENTITY EtherealPrint SYSTEM "./graphics/ethereal-print.png" NDATA PNG>
- <!ENTITY EtherealGUIPreferences SYSTEM "./graphics/ethereal-gui-preferences.png" NDATA PNG>
- <!ENTITY EtherealGUILayoutPreferences SYSTEM "./graphics/ethereal-gui-layout-preferences.png" NDATA PNG>
- <!ENTITY EtherealGUIColumnsPreferences SYSTEM "./graphics/ethereal-gui-columns-preferences.png" NDATA PNG>
- <!ENTITY EtherealGUIFontPreferences SYSTEM "./graphics/ethereal-gui-font-preferences.png" NDATA PNG>
- <!ENTITY EtherealGUIColorsPreferences SYSTEM "./graphics/ethereal-gui-colors-preferences.png" NDATA PNG>
- <!ENTITY EtherealCapturePreferences SYSTEM "./graphics/ethereal-capture-preferences.png" NDATA PNG>
- <!ENTITY EtherealPrintingPreferences SYSTEM "./graphics/ethereal-printing-preferences.png" NDATA PNG>
- <!ENTITY EtherealNameResolutionPreferences SYSTEM "./graphics/ethereal-nameresolution-preferences.png" NDATA PNG>
- <!ENTITY EtherealFilters SYSTEM "./graphics/ethereal-filters.png" NDATA PNG>
- <!ENTITY EtherealFileMenu SYSTEM "./graphics/ethereal-file-menu.png" NDATA PNG>
- <!ENTITY EtherealEditMenu SYSTEM "./graphics/ethereal-edit-menu.png" NDATA PNG>
- <!ENTITY EtherealViewMenu SYSTEM "./graphics/ethereal-view-menu.png" NDATA PNG>
- <!ENTITY EtherealGoMenu SYSTEM "./graphics/ethereal-go-menu.png" NDATA PNG>
- <!ENTITY EtherealCaptureMenu SYSTEM "./graphics/ethereal-capture-menu.png" NDATA PNG>
- <!ENTITY EtherealAnalyzeMenu SYSTEM "./graphics/ethereal-analyze-menu.png" NDATA PNG>
- <!ENTITY EtherealStatisticsMenu SYSTEM "./graphics/ethereal-statistics-menu.png" NDATA PNG>
- <!ENTITY EtherealHelpMenu SYSTEM "./graphics/ethereal-help-menu.png" NDATA PNG>
- <!ENTITY EtherealPacketPanePopupMenu SYSTEM "./graphics/ethereal-packet-pane-popup-menu.png" NDATA PNG>
- <!ENTITY EtherealDetailsPanePopupMenu SYSTEM "./graphics/ethereal-details-pane-popup-menu.png" NDATA PNG>
- <!ENTITY EtherealBytesPanePopupMenu SYSTEM "./graphics/ethereal-bytes-pane-popup-menu.png" NDATA PNG>
- <!ENTITY EtherealFilterAddExpression SYSTEM "./graphics/ethereal-filter-add-expression.png" NDATA PNG>
- <!ENTITY EtherealFilters2 SYSTEM "./graphics/ethereal-filters-2.png" NDATA PNG>
- <!ENTITY EtherealExportPlainDialog SYSTEM "./graphics/ethereal-export-plain.png" NDATA PNG>
- <!ENTITY EtherealExportPSDialog SYSTEM "./graphics/ethereal-export-ps.png" NDATA PNG>
- <!ENTITY EtherealExportPSMLDialog SYSTEM "./graphics/ethereal-export-psml.png" NDATA PNG>
- <!ENTITY EtherealExportPDMLDialog SYSTEM "./graphics/ethereal-export-pdml.png" NDATA PNG>
- <!ENTITY EtherealExportSelectedDialog SYSTEM "./graphics/ethereal-export-selected.png" NDATA PNG>
- <!ENTITY EtherealCaptureOptionsDialog SYSTEM "./graphics/ethereal-capture-options.png" NDATA PNG>
- <!ENTITY EtherealCaptureInfoDialog SYSTEM "./graphics/ethereal-capture-info.png" NDATA PNG>
- <!ENTITY EtherealMergeDialog SYSTEM "./graphics/ethereal-merge.png" NDATA PNG>
- <!ENTITY EtherealPacketRangeFrame SYSTEM "./graphics/ethereal-packet-range.png" NDATA PNG>
- <!ENTITY EtherealPacketFormatFrame SYSTEM "./graphics/ethereal-packet-format.png" NDATA PNG>
- <!ENTITY EtherealTimeReference SYSTEM "./graphics/ethereal-time-reference.png" NDATA PNG>
- <!ENTITY EtherealEnabledProtocols SYSTEM "./graphics/ethereal-enabled-protocols.png" NDATA PNG>
- <!ENTITY EtherealDecodeAs SYSTEM "./graphics/ethereal-decode-as.png" NDATA PNG>
- <!ENTITY EtherealDecodeAsShow SYSTEM "./graphics/ethereal-decode-as-show.png" NDATA PNG>
-
- <!-- Third Chapter Toolbar-->
- <!ENTITY EtherealToolbarCapture SYSTEM "./graphics/toolbar/capture_24.png" NDATA PNG>
- <!ENTITY EtherealToolbarCaptureFilters SYSTEM "./graphics/toolbar/cfilter_24.png" NDATA PNG>
- <!ENTITY EtherealToolbarDisplayFilters SYSTEM "./graphics/toolbar/dfilter_24.png" NDATA PNG>
- <!ENTITY EtherealToolbarAdd SYSTEM "./graphics/toolbar/stock_add_24.png" NDATA PNG>
- <!ENTITY EtherealToolbarGoLast SYSTEM "./graphics/toolbar/stock_bottom_24.png" NDATA PNG>
- <!ENTITY EtherealToolbarClose SYSTEM "./graphics/toolbar/stock_close_24.png" NDATA PNG>
- <!ENTITY EtherealToolbarColoringRules SYSTEM "./graphics/toolbar/stock_colorselector_24.png" NDATA PNG>
- <!ENTITY EtherealToolbarHelp SYSTEM "./graphics/toolbar/stock_help_24.png" NDATA PNG>
- <!ENTITY EtherealToolbarGoTo SYSTEM "./graphics/toolbar/stock_jump_to_24.png" NDATA PNG>
- <!ENTITY EtherealToolbarFindPrevious SYSTEM "./graphics/toolbar/stock_left_arrow_24.png" NDATA PNG>
- <!ENTITY EtherealToolbarOpen SYSTEM "./graphics/toolbar/stock_open_24.png" NDATA PNG>
- <!ENTITY EtherealToolbarPreferences SYSTEM "./graphics/toolbar/stock_preferences_24.png" NDATA PNG>
- <!ENTITY EtherealToolbarPrint SYSTEM "./graphics/toolbar/stock_print_24.png" NDATA PNG>
- <!ENTITY EtherealToolbarProperties SYSTEM "./graphics/toolbar/stock_properties_24.png" NDATA PNG>
- <!ENTITY EtherealToolbarReload SYSTEM "./graphics/toolbar/stock_refresh_24.png" NDATA PNG>
- <!ENTITY EtherealToolbarFindNext SYSTEM "./graphics/toolbar/stock_right_arrow_24.png" NDATA PNG>
- <!ENTITY EtherealToolbarSave SYSTEM "./graphics/toolbar/stock_save_24.png" NDATA PNG>
- <!ENTITY EtherealToolbarSaveAs SYSTEM "./graphics/toolbar/stock_save_as_24.png" NDATA PNG>
- <!ENTITY EtherealToolbarFind SYSTEM "./graphics/toolbar/stock_search_24.png" NDATA PNG>
- <!ENTITY EtherealToolbarStop SYSTEM "./graphics/toolbar/stock_stop_24.png" NDATA PNG>
- <!ENTITY EtherealToolbarGoFirst SYSTEM "./graphics/toolbar/stock_top_24.png" NDATA PNG>
- <!ENTITY EtherealToolbarZoom100 SYSTEM "./graphics/toolbar/stock_zoom_1_24.png" NDATA PNG>
- <!ENTITY EtherealToolbarZoomIn SYSTEM "./graphics/toolbar/stock_zoom_in_24.png" NDATA PNG>
- <!ENTITY EtherealToolbarZoomOut SYSTEM "./graphics/toolbar/stock_zoom_out_24.png" NDATA PNG>
-
- <!-- Third Chapter Statistics -->
- <!ENTITY EtherealStatsSummary SYSTEM "./graphics/ethereal-stats-summary.png" NDATA PNG>
- <!ENTITY EtherealStatsHierarchy SYSTEM "./graphics/ethereal-stats-hierarchy.png" NDATA PNG>
- <!ENTITY EtherealStatsEndpoints SYSTEM "./graphics/ethereal-stats-endpoints.png" NDATA PNG>
- <!ENTITY EtherealStatsConversations SYSTEM "./graphics/ethereal-stats-conversations.png" NDATA PNG>
- <!ENTITY EtherealStatsIOGraphs SYSTEM "./graphics/ethereal-stats-iographs.png" NDATA PNG>
- <!ENTITY EtherealStatsSrtDcerpcFilter SYSTEM "./graphics/ethereal-stats-srt-dcerpc-filter.png" NDATA PNG>
- <!ENTITY EtherealStatsSrtDcerpc SYSTEM "./graphics/ethereal-stats-srt-dcerpc.png" NDATA PNG>
-
- <!-- Fifth Chapter -->
-
- <!-- Sixth Chapter -->
-
- <!-- Appendices etc -->
- <!ENTITY EtherealFormatError SYSTEM "./graphics/ethereal-error-open.png" NDATA PNG>
- <!ENTITY EtherealFormatError SYSTEM "./graphics/ethereal-error-open.png" NDATA PNG>
- <!ENTITY EtherealSaveError SYSTEM "./graphics/ethereal-save-error.png" NDATA PNG>
-
-
-<!-- These are the actual files that make up the document -->
- <!ENTITY BookMetaInformation SYSTEM "ug-src/EUG_meta_info.xml">
- <!ENTITY Preface SYSTEM "ug-src/EUG_preface.xml">
- <!ENTITY ChapterIntroduction SYSTEM "ug-src/EUG_chapter_introduction.xml">
- <!ENTITY ChapterBuildInstall SYSTEM "ug-src/EUG_chapter_build_install.xml">
- <!ENTITY ChapterUse SYSTEM "ug-src/EUG_chapter_use.xml">
- <!ENTITY ChapterCapture SYSTEM "ug-src/EUG_chapter_capture.xml">
- <!ENTITY ChapterIo SYSTEM "ug-src/EUG_chapter_io.xml">
- <!ENTITY ChapterWork SYSTEM "ug-src/EUG_chapter_work.xml">
- <!ENTITY ChapterAdvanced SYSTEM "ug-src/EUG_chapter_advanced.xml">
- <!ENTITY ChapterStatistics SYSTEM "ug-src/EUG_chapter_statistics.xml">
- <!ENTITY ChapterCustomize SYSTEM "ug-src/EUG_chapter_customize.xml">
- <!ENTITY ChapterTroubleshoot SYSTEM "ug-src/EUG_chapter_troubleshoot.xml">
- <!ENTITY AppMessages SYSTEM "ug-src/EUG_app_messages.xml">
- <!ENTITY AppFiles SYSTEM "ug-src/EUG_app_files.xml">
- <!ENTITY AppProtocols SYSTEM "ug-src/EUG_app_protocols.xml">
- <!ENTITY AppHowItWorks SYSTEM "ug-src/EUG_app_howitworks.xml">
- <!ENTITY AppTools SYSTEM "ug-src/EUG_app_tools.xml">
- <!ENTITY AppGFDPL SYSTEM "GFDPL_appendix.xml">
- <!ENTITY ProtoList SYSTEM "protocols.xml">
-
-]>
-
-<book>
- <title>&DocumentTitle;</title>
- <subtitle>&DocumentSubTitle;</subtitle>
- <!-- -->
- &BookMetaInformation;
- &Preface;
- &ChapterIntroduction;
- &ChapterBuildInstall;
- &ChapterUse;
- &ChapterCapture;
- &ChapterIo;
- &ChapterWork;
- &ChapterAdvanced;
- <!-- -->
- &ChapterStatistics;
- &ChapterCustomize;
-
- <!-- Removed, as this chapter has to be reworked first -->
- <!-- &ChapterTroubleshoot; -->
-
- <!-- Removed, as this chapter is much too long and should form it's own document -->
- <!-- &FilterFields; -->
-
- <!-- Removed, as there are a lot more of warnings and messages right now, and
- the warnings and messages should be self explanatory. -->
- <!-- &AppMessages; -->
-
- &AppFiles;
- &AppProtocols;
- &AppTools;
- <!-- Removed, as this chapter is not finished
- &AppHowItWorks;
- -->
- &AppGFDPL;
- <!-- Removed, as these chapters must be reworked -->
- <!--
- &Glossary;
- &Index; -->
-</book>
+<?xml version="1.0"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ + +<!-- $Id$ --> + +<!-- +BIOGRAPHICAL SECTION +-Use this section to encode all biographical information +--> + +<!-- Author's Names --> + <!ENTITY AuthorFullName "Richard Sharpe"> + <!ENTITY AuthorFirstName "Richard"> + <!ENTITY AuthorOtherName ""> + <!ENTITY AuthorSurname "Sharpe"> + + <!ENTITY AuthorFullName2 "Ed Warnicke"> + <!ENTITY AuthorFirstName2 "Ed"> + <!ENTITY AuthorOtherName2 ""> + <!ENTITY AuthorSurname2 "Warnicke"> + + <!ENTITY AuthorFullName3 "Ulf Lamping"> + <!ENTITY AuthorFirstName3 "Ulf"> + <!ENTITY AuthorOtherName3 ""> + <!ENTITY AuthorSurname3 "Lamping"> + +<!--Author's Affiliation --> + <!ENTITY AuthorShortAffiliation ""> + <!ENTITY AuthorJobTitle "Director"> + <!ENTITY AuthorOrgName "NS Computer Software and Services P/L"> + <!ENTITY AuthorOrgDiv ""> + <!ENTITY AuthorEmail "rsharpe[AT]ns.aus.com"> + + <!ENTITY AuthorShortAffiliation2 ""> + <!ENTITY AuthorJobTitle2 ""> + <!ENTITY AuthorOrgName2 ""> + <!ENTITY AuthorOrgDiv2 ""> + <!ENTITY AuthorEmail2 "hagbard[AT]physics.rutgers.edu"> + + <!ENTITY AuthorShortAffiliation3 ""> + <!ENTITY AuthorJobTitle3 ""> + <!ENTITY AuthorOrgName3 ""> + <!ENTITY AuthorOrgDiv3 ""> + <!ENTITY AuthorEmail3 "ulf.lamping[AT]web.de"> + + + + +<!-- +DOCUMENT SECTION +-Use this section to encode all document information +--> + + <!ENTITY DocumentTitle "<application>Ethereal</application> User's Guide"> + <!ENTITY DocumentSubTitle "&DocumentVersion; for Ethereal &EtherealCurrentVersion;"> + <!ENTITY DocumentTitleAbbreviation "EUG"> + + <!ENTITY DocumentCopyrightHolder1 "Richard Sharpe"> + <!ENTITY DocumentCopyrightHolder2 "Ed Warnicke"> + <!ENTITY DocumentCopyrightHolder3 "Ulf Lamping"> + <!ENTITY DocumentCopyrightYear "2004"> + + <!ENTITY DocumentEdition "Third "> + <!ENTITY DocumentVersion "V2.00"> + <!ENTITY DocumentPubDate "2004"> + +<!ENTITY DocumentLegalNotice "<para>Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts.</para><para>All logos and trademarks in this document are property of their respective owner.</para>"> + +<!-- +Ethereal Info +--> + <!ENTITY EtherealCurrentVersion "0.10.5"> + <!ENTITY EtherealNextMinorVersion "0.10.6"> + <!ENTITY EtherealWebSite "http://www.ethereal.com"> + <!ENTITY EtherealDownloadPage "&EtherealWebSite;/download.html"> + <!ENTITY EtherealBinariesPage "&EtherealWebSite;/download.html#binaries"> + <!ENTITY EtherealAuthorsPage "&EtherealWebSite;/introduction.html#authors"> + <!ENTITY EtherealProtocolsPage "&EtherealWebSite;/docs/dfref/"> + <!ENTITY EtherealFAQPage "&EtherealWebSite;/faq.html"> + <!ENTITY EtherealFAQPromiscPage "&EtherealWebSite;/faq#promiscsniff"> + <!ENTITY EtherealMediaPage "&EtherealWebSite;/media.html"> + <!ENTITY EtherealCurrentVersionTarFile "0.10.5"> + + <!ENTITY EtherealDevMailList "ethereal-dev[AT]ethereal.com"> + <!ENTITY EtherealUsersMailList "ethereal-users[AT]ethereal.com"> + + +<!-- +Winpcap Info +--> + <!ENTITY WinPcapWebsite "http://winpcap.polito.it"> + <!ENTITY WinPcapDownloadWebsite "http://winpcap.polito.it/install/Default.htm"> + +<!-- +Gnu info +--> + <!ENTITY GPLWebsite "http://www.gnu.org/copyleft/gpl.html"> + +<!-- Self referential info +--> + + <!ENTITY LatestVersionWebsite "http://www.richardsharpe.com/richard/ethereal/user-guide/book1.html" > + <!ENTITY LatestVersionPDFWebsiteA4 "http://www.richardsharpe.com/richard/ethereal/user-guide/user-guide-a4.pdf" > + <!ENTITY LatestVersionPDFWebsiteUSLetter "http://www.richardsharpe.com/richard/ethereal/user-guide/user-guide-usletter.pdf" > +<!-- +FILE SECTION +-Use this section to specify the files that make up the book. Use FPI (public identifiers) +--> +<!-- These refer to graphics files and figures contained in the document --> + <!-- --> + <!ENTITY EtherealLogo SYSTEM "./graphics/ethereal-logo.png" NDATA PNG> + + <!-- 1st Chapter --> + <!ENTITY EtherealMain1 SYSTEM "./graphics/ethereal-main.png" NDATA PNG> + + <!-- 2nd Chapter --> + + <!-- Third Chapter --> + <!ENTITY EtherealEmpty SYSTEM "./graphics/ethereal-empty.png" NDATA PNG> + <!ENTITY EtherealThreePane1 SYSTEM "./graphics/ethereal-3pane.png" NDATA PNG> + <!ENTITY EtherealMenuOnly SYSTEM "./graphics/ethereal-menu.png" NDATA PNG> + <!ENTITY EtherealMainToolbar SYSTEM "./graphics/ethereal-main-toolbar.png" NDATA PNG> + <!ENTITY EtherealFilterToolbar SYSTEM "./graphics/ethereal-filter-toolbar.png" NDATA PNG> + <!ENTITY EtherealListPane SYSTEM "./graphics/ethereal-list-pane.png" NDATA PNG> + <!ENTITY EtherealDetailsPane SYSTEM "./graphics/ethereal-details-pane.png" NDATA PNG> + <!ENTITY EtherealBytesPane SYSTEM "./graphics/ethereal-bytes-pane.png" NDATA PNG> + <!ENTITY EtherealBytesPaneTabs SYSTEM "./graphics/ethereal-bytes-pane-tabs.png" NDATA PNG> + <!ENTITY EtherealStatusbarEmpty SYSTEM "./graphics/ethereal-statusbar-empty.png" NDATA PNG> + <!ENTITY EtherealStatusbarLoaded SYSTEM "./graphics/ethereal-statusbar-loaded.png" NDATA PNG> + <!ENTITY EtherealStatusbarSelected SYSTEM "./graphics/ethereal-statusbar-selected.png" NDATA PNG> + <!ENTITY EtherealSaveAs SYSTEM "./graphics/ethereal-save-as.png" NDATA PNG> + <!ENTITY EtherealOpen SYSTEM "./graphics/ethereal-open.png" NDATA PNG> + <!ENTITY EtherealPacketSelected1 SYSTEM "./graphics/ethereal-packet-selected.png" NDATA PNG> + <!ENTITY EtherealPacketSepView SYSTEM "./graphics/ethereal-packet-sep-win.png" NDATA PNG> + <!ENTITY EtherealFilterTCP SYSTEM "./graphics/ethereal-display-filter-tcp.png" NDATA PNG> + <!ENTITY EtherealColoringRulesDialog SYSTEM "./graphics/ethereal-coloring-rules-dialog.png" NDATA PNG> + <!ENTITY EtherealEditColorDialog SYSTEM "./graphics/ethereal-edit-color-rule-dialog.png" NDATA PNG> + <!ENTITY EtherealChooseColorDialog SYSTEM "./graphics/ethereal-choose-color-rule.png" NDATA PNG> + <!ENTITY EtherealFollowStream SYSTEM "./graphics/ethereal-follow-stream.png" NDATA PNG> + <!ENTITY EtherealFindPacket SYSTEM "./graphics/ethereal-find-packet.png" NDATA PNG> + <!ENTITY EtherealGoToPacket SYSTEM "./graphics/ethereal-goto-packet.png" NDATA PNG> + <!ENTITY EtherealPrint SYSTEM "./graphics/ethereal-print.png" NDATA PNG> + <!ENTITY EtherealGUIPreferences SYSTEM "./graphics/ethereal-gui-preferences.png" NDATA PNG> + <!ENTITY EtherealGUILayoutPreferences SYSTEM "./graphics/ethereal-gui-layout-preferences.png" NDATA PNG> + <!ENTITY EtherealGUIColumnsPreferences SYSTEM "./graphics/ethereal-gui-columns-preferences.png" NDATA PNG> + <!ENTITY EtherealGUIFontPreferences SYSTEM "./graphics/ethereal-gui-font-preferences.png" NDATA PNG> + <!ENTITY EtherealGUIColorsPreferences SYSTEM "./graphics/ethereal-gui-colors-preferences.png" NDATA PNG> + <!ENTITY EtherealCapturePreferences SYSTEM "./graphics/ethereal-capture-preferences.png" NDATA PNG> + <!ENTITY EtherealPrintingPreferences SYSTEM "./graphics/ethereal-printing-preferences.png" NDATA PNG> + <!ENTITY EtherealNameResolutionPreferences SYSTEM "./graphics/ethereal-nameresolution-preferences.png" NDATA PNG> + <!ENTITY EtherealFilters SYSTEM "./graphics/ethereal-filters.png" NDATA PNG> + <!ENTITY EtherealFileMenu SYSTEM "./graphics/ethereal-file-menu.png" NDATA PNG> + <!ENTITY EtherealEditMenu SYSTEM "./graphics/ethereal-edit-menu.png" NDATA PNG> + <!ENTITY EtherealViewMenu SYSTEM "./graphics/ethereal-view-menu.png" NDATA PNG> + <!ENTITY EtherealGoMenu SYSTEM "./graphics/ethereal-go-menu.png" NDATA PNG> + <!ENTITY EtherealCaptureMenu SYSTEM "./graphics/ethereal-capture-menu.png" NDATA PNG> + <!ENTITY EtherealAnalyzeMenu SYSTEM "./graphics/ethereal-analyze-menu.png" NDATA PNG> + <!ENTITY EtherealStatisticsMenu SYSTEM "./graphics/ethereal-statistics-menu.png" NDATA PNG> + <!ENTITY EtherealHelpMenu SYSTEM "./graphics/ethereal-help-menu.png" NDATA PNG> + <!ENTITY EtherealPacketPanePopupMenu SYSTEM "./graphics/ethereal-packet-pane-popup-menu.png" NDATA PNG> + <!ENTITY EtherealDetailsPanePopupMenu SYSTEM "./graphics/ethereal-details-pane-popup-menu.png" NDATA PNG> + <!ENTITY EtherealBytesPanePopupMenu SYSTEM "./graphics/ethereal-bytes-pane-popup-menu.png" NDATA PNG> + <!ENTITY EtherealFilterAddExpression SYSTEM "./graphics/ethereal-filter-add-expression.png" NDATA PNG> + <!ENTITY EtherealFilters2 SYSTEM "./graphics/ethereal-filters-2.png" NDATA PNG> + <!ENTITY EtherealExportPlainDialog SYSTEM "./graphics/ethereal-export-plain.png" NDATA PNG> + <!ENTITY EtherealExportPSDialog SYSTEM "./graphics/ethereal-export-ps.png" NDATA PNG> + <!ENTITY EtherealExportPSMLDialog SYSTEM "./graphics/ethereal-export-psml.png" NDATA PNG> + <!ENTITY EtherealExportPDMLDialog SYSTEM "./graphics/ethereal-export-pdml.png" NDATA PNG> + <!ENTITY EtherealExportSelectedDialog SYSTEM "./graphics/ethereal-export-selected.png" NDATA PNG> + <!ENTITY EtherealCaptureOptionsDialog SYSTEM "./graphics/ethereal-capture-options.png" NDATA PNG> + <!ENTITY EtherealCaptureInfoDialog SYSTEM "./graphics/ethereal-capture-info.png" NDATA PNG> + <!ENTITY EtherealMergeDialog SYSTEM "./graphics/ethereal-merge.png" NDATA PNG> + <!ENTITY EtherealPacketRangeFrame SYSTEM "./graphics/ethereal-packet-range.png" NDATA PNG> + <!ENTITY EtherealPacketFormatFrame SYSTEM "./graphics/ethereal-packet-format.png" NDATA PNG> + <!ENTITY EtherealTimeReference SYSTEM "./graphics/ethereal-time-reference.png" NDATA PNG> + <!ENTITY EtherealEnabledProtocols SYSTEM "./graphics/ethereal-enabled-protocols.png" NDATA PNG> + <!ENTITY EtherealDecodeAs SYSTEM "./graphics/ethereal-decode-as.png" NDATA PNG> + <!ENTITY EtherealDecodeAsShow SYSTEM "./graphics/ethereal-decode-as-show.png" NDATA PNG> + + <!-- Third Chapter Toolbar--> + <!ENTITY EtherealToolbarCapture SYSTEM "./graphics/toolbar/capture_24.png" NDATA PNG> + <!ENTITY EtherealToolbarCaptureFilters SYSTEM "./graphics/toolbar/cfilter_24.png" NDATA PNG> + <!ENTITY EtherealToolbarDisplayFilters SYSTEM "./graphics/toolbar/dfilter_24.png" NDATA PNG> + <!ENTITY EtherealToolbarAdd SYSTEM "./graphics/toolbar/stock_add_24.png" NDATA PNG> + <!ENTITY EtherealToolbarGoLast SYSTEM "./graphics/toolbar/stock_bottom_24.png" NDATA PNG> + <!ENTITY EtherealToolbarClose SYSTEM "./graphics/toolbar/stock_close_24.png" NDATA PNG> + <!ENTITY EtherealToolbarColoringRules SYSTEM "./graphics/toolbar/stock_colorselector_24.png" NDATA PNG> + <!ENTITY EtherealToolbarHelp SYSTEM "./graphics/toolbar/stock_help_24.png" NDATA PNG> + <!ENTITY EtherealToolbarGoTo SYSTEM "./graphics/toolbar/stock_jump_to_24.png" NDATA PNG> + <!ENTITY EtherealToolbarFindPrevious SYSTEM "./graphics/toolbar/stock_left_arrow_24.png" NDATA PNG> + <!ENTITY EtherealToolbarOpen SYSTEM "./graphics/toolbar/stock_open_24.png" NDATA PNG> + <!ENTITY EtherealToolbarPreferences SYSTEM "./graphics/toolbar/stock_preferences_24.png" NDATA PNG> + <!ENTITY EtherealToolbarPrint SYSTEM "./graphics/toolbar/stock_print_24.png" NDATA PNG> + <!ENTITY EtherealToolbarProperties SYSTEM "./graphics/toolbar/stock_properties_24.png" NDATA PNG> + <!ENTITY EtherealToolbarReload SYSTEM "./graphics/toolbar/stock_refresh_24.png" NDATA PNG> + <!ENTITY EtherealToolbarFindNext SYSTEM "./graphics/toolbar/stock_right_arrow_24.png" NDATA PNG> + <!ENTITY EtherealToolbarSave SYSTEM "./graphics/toolbar/stock_save_24.png" NDATA PNG> + <!ENTITY EtherealToolbarSaveAs SYSTEM "./graphics/toolbar/stock_save_as_24.png" NDATA PNG> + <!ENTITY EtherealToolbarFind SYSTEM "./graphics/toolbar/stock_search_24.png" NDATA PNG> + <!ENTITY EtherealToolbarStop SYSTEM "./graphics/toolbar/stock_stop_24.png" NDATA PNG> + <!ENTITY EtherealToolbarGoFirst SYSTEM "./graphics/toolbar/stock_top_24.png" NDATA PNG> + <!ENTITY EtherealToolbarZoom100 SYSTEM "./graphics/toolbar/stock_zoom_1_24.png" NDATA PNG> + <!ENTITY EtherealToolbarZoomIn SYSTEM "./graphics/toolbar/stock_zoom_in_24.png" NDATA PNG> + <!ENTITY EtherealToolbarZoomOut SYSTEM "./graphics/toolbar/stock_zoom_out_24.png" NDATA PNG> + + <!-- Third Chapter Statistics --> + <!ENTITY EtherealStatsSummary SYSTEM "./graphics/ethereal-stats-summary.png" NDATA PNG> + <!ENTITY EtherealStatsHierarchy SYSTEM "./graphics/ethereal-stats-hierarchy.png" NDATA PNG> + <!ENTITY EtherealStatsEndpoints SYSTEM "./graphics/ethereal-stats-endpoints.png" NDATA PNG> + <!ENTITY EtherealStatsConversations SYSTEM "./graphics/ethereal-stats-conversations.png" NDATA PNG> + <!ENTITY EtherealStatsIOGraphs SYSTEM "./graphics/ethereal-stats-iographs.png" NDATA PNG> + <!ENTITY EtherealStatsSrtDcerpcFilter SYSTEM "./graphics/ethereal-stats-srt-dcerpc-filter.png" NDATA PNG> + <!ENTITY EtherealStatsSrtDcerpc SYSTEM "./graphics/ethereal-stats-srt-dcerpc.png" NDATA PNG> + + <!-- Fifth Chapter --> + + <!-- Sixth Chapter --> + + <!-- Appendices etc --> + <!ENTITY EtherealFormatError SYSTEM "./graphics/ethereal-error-open.png" NDATA PNG> + <!ENTITY EtherealFormatError SYSTEM "./graphics/ethereal-error-open.png" NDATA PNG> + <!ENTITY EtherealSaveError SYSTEM "./graphics/ethereal-save-error.png" NDATA PNG> + + +<!-- These are the actual files that make up the document --> + <!ENTITY BookMetaInformation SYSTEM "ug-src/EUG_meta_info.xml"> + <!ENTITY Preface SYSTEM "ug-src/EUG_preface.xml"> + <!ENTITY ChapterIntroduction SYSTEM "ug-src/EUG_chapter_introduction.xml"> + <!ENTITY ChapterBuildInstall SYSTEM "ug-src/EUG_chapter_build_install.xml"> + <!ENTITY ChapterUse SYSTEM "ug-src/EUG_chapter_use.xml"> + <!ENTITY ChapterCapture SYSTEM "ug-src/EUG_chapter_capture.xml"> + <!ENTITY ChapterIo SYSTEM "ug-src/EUG_chapter_io.xml"> + <!ENTITY ChapterWork SYSTEM "ug-src/EUG_chapter_work.xml"> + <!ENTITY ChapterAdvanced SYSTEM "ug-src/EUG_chapter_advanced.xml"> + <!ENTITY ChapterStatistics SYSTEM "ug-src/EUG_chapter_statistics.xml"> + <!ENTITY ChapterCustomize SYSTEM "ug-src/EUG_chapter_customize.xml"> + <!ENTITY ChapterTroubleshoot SYSTEM "ug-src/EUG_chapter_troubleshoot.xml"> + <!ENTITY AppMessages SYSTEM "ug-src/EUG_app_messages.xml"> + <!ENTITY AppFiles SYSTEM "ug-src/EUG_app_files.xml"> + <!ENTITY AppProtocols SYSTEM "ug-src/EUG_app_protocols.xml"> + <!ENTITY AppHowItWorks SYSTEM "ug-src/EUG_app_howitworks.xml"> + <!ENTITY AppTools SYSTEM "ug-src/EUG_app_tools.xml"> + <!ENTITY AppGFDPL SYSTEM "GFDPL_appendix.xml"> + <!ENTITY ProtoList SYSTEM "protocols.xml"> + +]> + +<book> + <title>&DocumentTitle;</title> + <subtitle>&DocumentSubTitle;</subtitle> + <!-- --> + &BookMetaInformation; + &Preface; + &ChapterIntroduction; + &ChapterBuildInstall; + &ChapterUse; + &ChapterCapture; + &ChapterIo; + &ChapterWork; + &ChapterAdvanced; + <!-- --> + &ChapterStatistics; + &ChapterCustomize; + + <!-- Removed, as this chapter has to be reworked first --> + <!-- &ChapterTroubleshoot; --> + + <!-- Removed, as this chapter is much too long and should form it's own document --> + <!-- &FilterFields; --> + + <!-- Removed, as there are a lot more of warnings and messages right now, and + the warnings and messages should be self explanatory. --> + <!-- &AppMessages; --> + + &AppFiles; + &AppProtocols; + &AppTools; + <!-- Removed, as this chapter is not finished + &AppHowItWorks; + --> + &AppGFDPL; + <!-- Removed, as these chapters must be reworked --> + <!-- + &Glossary; + &Index; --> +</book> |