Lucent Technologies Ethereal User Manual

Ethereal User's Guide

V2.0.2 (16376) for Ethereal 0.10.12

Richard Sharpe, NS Computer Software and Services P/L

Ed Warnicke,

Ulf Lamping,

Ethereal User's Guide: V2.0.2 (16376) for Ethereal 0.10.12

by Richard Sharpe, Ed Warnicke, and Ulf Lamping
Copyright © 2004-2005 Richard SharpeEd WarnickeUlf Lamping

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License, Version 2 or any
later version published by the Free Software Foundation.

All logos and trademarks in this document are property of their respective owner.

Table of Contents

Preface ............................................................................................................................. viii

1. Foreword .............................................................................................................. viii

2. Who should read this document? ................................................................................. ix

3. Acknowledgements .................................................................................................... x

4. About this document ................................................................................................. xi

5. Where to get the latest copy of this document? .............................................................. xii

6. Providing feedback about this document ..................................................................... xiii

1. Introduction ...................................................................................................................... 1

1.1. What is Ethereal? .................................................................................................... 1

1.1.1. Some intended purposes ................................................................................. 1

1.1.2. Features ...................................................................................................... 1

1.1.3. Live capture from many different network media ................................................ 2

1.1.4. Import files from many other capture programs .................................................. 2

1.1.5. Export files for many other capture programs ..................................................... 2

1.1.6. Many protocol decoders ................................................................................. 2

1.1.7. Open Source Software ................................................................................... 2

1.1.8. What Ethereal is not ...................................................................................... 3

1.2. Platforms Ethereal runs on ........................................................................................ 4

1.2.1. Unix ........................................................................................................... 4

1.2.2. Linux ......................................................................................................... 4

1.2.3. Microsoft Windows ....................................................................................... 5

1.3. Where to get Ethereal? ............................................................................................. 6

1.4. A rose by any other name ......................................................................................... 7

1.5. A brief history of Ethereal ......................................................................................... 8

1.6. Development and maintenance of Ethereal ................................................................... 9

1.7. Reporting problems and getting help ..........................................................................10

1.7.1. Website .....................................................................................................10

1.7.2. Wiki ..........................................................................................................10

1.7.3. FAQ ..........................................................................................................10

1.7.4. Mailing Lists ..............................................................................................10

1.7.5. Reporting Problems ......................................................................................11

1.7.6. Reporting Crashes on UNIX/Linux platforms ....................................................11

1.7.7. Reporting Crashes on Windows platforms ........................................................12

2. Building and Installing Ethereal ...........................................................................................14

2.1. Introduction ..........................................................................................................14

2.2. Obtaining the source and binary distributions ...............................................................15

2.3. Before you build Ethereal under UNIX .......................................................................16

2.4. Building Ethereal from source under UNIX .................................................................19

2.5. Installing the binaries under UNIX ............................................................................21

2.5.1. Installing from rpm's under RedHat and alike ....................................................21

2.5.2. Installing from deb's under Debian ..................................................................21

2.6. Troubleshooting during the install on Unix ..................................................................22

2.7. Building from source under Windows ........................................................................23

2.8. Installing Ethereal under Windows ............................................................................24

2.8.1. Install Ethereal ............................................................................................24

2.8.2. Install WinPcap ...........................................................................................25

2.8.3. Update Ethereal ...........................................................................................26

2.8.4. Update WinPcap ..........................................................................................26

2.8.5. Uninstall Ethereal ........................................................................................26

2.8.6. Uninstall WinPcap .......................................................................................27

3. User Interface ..................................................................................................................29

3.1. Introduction ..........................................................................................................29

3.2. Start Ethereal .........................................................................................................30

3.3. The Main window ..................................................................................................31

3.4. The Menu .............................................................................................................33

3.5. The "File" menu .....................................................................................................34

3.6. The "Edit" menu ....................................................................................................37

iv

Ethereal User's Guide

3.7. The "View" menu ...................................................................................................39

3.8. The "Go" menu ......................................................................................................42

3.9. The "Capture" menu ...............................................................................................44

3.10. The "Analyze" menu .............................................................................................46

3.11. The "Statistics" menu ............................................................................................48

3.12. The "Help" menu ..................................................................................................50

3.13. The "Main" toolbar ...............................................................................................52

3.14. The "Filter" toolbar ...............................................................................................55

3.15. The "Packet List" pane ..........................................................................................56

3.16. The "Packet Details" pane ......................................................................................57

3.17. The "Packet Bytes" pane ........................................................................................58

3.18. The Statusbar .......................................................................................................59

4. Capturing Live Network Data .............................................................................................61

4.1. Introduction ..........................................................................................................61

4.2. Prerequisites ..........................................................................................................62

4.3. Start Capturing ......................................................................................................63

4.4. The "Capture Interfaces" dialog box ...........................................................................64

4.5. The "Capture Options" dialog box .............................................................................65

4.5.1. Capture frame .............................................................................................65

4.5.2. Capture File(s) frame ....................................................................................67

4.5.3. Stop Capture... frame ....................................................................................67

4.5.4. Display Options frame ..................................................................................68

4.5.5. Name Resolution frame ................................................................................68

4.5.6. Buttons ......................................................................................................68

4.6. Capture files and file modes .....................................................................................69

4.7. Link-layer header type ............................................................................................71

4.8. Filtering while capturing ..........................................................................................72

4.9. While a Capture is running ... ...................................................................................74

4.9.1. Stop the running capture ...............................................................................74

4.9.2. Restart a running capture ...............................................................................75

5. File Input / Output and Printing ...........................................................................................77

5.1. Introduction ..........................................................................................................77

5.2. Open capture files ..................................................................................................78

5.2.1. The "Open Capture File" dialog box ................................................................78

5.2.2. Input File Formats ........................................................................................79

5.3. Saving captured packets ..........................................................................................81

5.3.1. The "Save Capture File As" dialog box ............................................................81

5.3.2. Output File Formats .....................................................................................83

5.4. Merging capture files ..............................................................................................84

5.4.1. The "Merge with Capture File" dialog box ........................................................84

5.5. File Sets ...............................................................................................................86

5.5.1. The "List Files" dialog box ............................................................................86

5.6. Exporting data .......................................................................................................87

5.6.1. The "Export as Plain Text File" dialog box .......................................................87

5.6.2. The "Export as PostScript File" dialog box .......................................................87

5.6.3. The "Export as CSV (Comma Seperated Values) File" dialog box .........................88

5.6.4. The "Export as PSML File" dialog box ............................................................88

5.6.5. The "Export as PDML File" dialog box ............................................................89

5.6.6. The "Export selected packet bytes" dialog box ...................................................90

5.7. Printing packets .....................................................................................................92

5.7.1. The "Print" dialog box ..................................................................................92

5.8. The Packet Range frame ..........................................................................................94

5.9. The Packet Format frame .........................................................................................95

6. Working with captured packets ............................................................................................97

6.1. Viewing packets you have captured ...........................................................................97

6.2. Filtering packets while viewing ............................................................................... 103

6.3. Building display filter expressions ...........................................................................105

6.3.1. Display filter fields ....................................................................................105

6.3.2. Comparing values ...................................................................................... 105

6.3.3. Combining expressions ...............................................................................106

6.3.4. A common mistake .................................................................................... 108

6.4. The "Filter Expression" dialog box .......................................................................... 109

6.5. Defining and saving filters ..................................................................................... 111

v

Ethereal User's Guide

6.6. Finding packets .................................................................................................... 113

6.6.1. The "Find Packet" dialog box ....................................................................... 113

6.6.2. The "Find Next" command .......................................................................... 114

6.6.3. The "Find Previous" command ..................................................................... 114

6.7. Go to a specific packet ..........................................................................................115

6.7.1. The "Go Back" command ............................................................................115

6.7.2. The "Go Forward" command ....................................................................... 115

6.7.3. The "Go to Packet" dialog box .....................................................................115

6.7.4. The "Go to Corresponding Packet" command ..................................................115

6.7.5. The "Go to First Packet" command ............................................................... 115

6.7.6. The "Go to Last Packet" command ................................................................ 115

6.8. Marking packets ................................................................................................... 116

6.9. Time display formats and time references ................................................................. 117

6.9.1. Packet time referencing ...............................................................................117

7. Advanced Features .......................................................................................................... 120

7.1. Introduction ........................................................................................................ 120

7.2. Following TCP streams .........................................................................................121

7.2.1. The "Follow TCP stream" dialog box ............................................................121

7.3. Packet Reassembling ............................................................................................ 123

7.3.1. What is it? ................................................................................................123

7.3.2. How Ethereal handles it .............................................................................. 123

7.3.3. Reassembling is disabled by default! ............................................................. 123

7.4. Name Resolution ..................................................................................................124

7.4.1. Ethernet name resolution (MAC layer) ........................................................... 124

7.4.2. IP name resolution (network layer) ................................................................ 124

7.4.3. IPX name resolution (network layer) ............................................................. 125

7.4.4. TCP/UDP port name resolution (transport layer) ..............................................125

8. Statistics ....................................................................................................................... 127

8.1. Introduction ........................................................................................................ 127

8.2. The "Summary" window ........................................................................................128

8.3. The "Protocol Hierarchy" window ........................................................................... 130

8.4. Endpoints ........................................................................................................... 132

8.4.1. What is an Endpoint? .................................................................................. 132

8.4.2. The "Endpoints" window ............................................................................. 132

8.4.3. The protocol specific "Endpoint List" windows ............................................... 133

8.5. Conversations ......................................................................................................134

8.5.1. What is a Conversation? .............................................................................. 134

8.5.2. The "Conversations" window ....................................................................... 134

8.5.3. The protocol specific "Conversation List" windows .......................................... 134

8.6. The "IO Graphs" window ....................................................................................... 135

8.7. Service Response Time ......................................................................................... 137

8.7.1. The "Service Response Time DCE-RPC" window ............................................137

8.8. The protocol specific statistics windows ................................................................... 139

9. Customizing Ethereal ...................................................................................................... 141

9.1. Introduction ........................................................................................................ 141

9.2. Start Ethereal from the command line .......................................................................142

9.3. Packet colorization ............................................................................................... 146

9.4. Control Protocol dissection .................................................................................... 149

9.4.1. The "Enabled Protocols" dialog box .............................................................. 149

9.4.2. User Specified Decodes ..............................................................................151

9.4.3. Show User Specified Decodes ...................................................................... 152

9.5. Preferences .........................................................................................................153

A. Configuration (and other) Files and Folders .........................................................................156

A.1. Windows folders .................................................................................................159

A.1.1. Windows profiles ...................................................................................... 159

A.1.2. Windows NT/2000/XP roaming profiles ........................................................160

A.1.3. Windows temporary folder ......................................................................... 160

B. Protocols and Protocol Fields ........................................................................................... 162

C. Related command line tools ............................................................................................. 163

C.1. Introduction ........................................................................................................ 163

C.2. tcpdump: Capturing with tcpdump for viewing with Ethereal ...................................... 164

C.3. tethereal: Terminal-based Ethereal .........................................................................165

C.4. capinfos: Print information about capture files .......................................................... 166

vi

Ethereal User's Guide

C.5. editcap: Edit capture files ..................................................................................... 167

C.6. mergecap: Merging multiple capture files into one .................................................... 170

C.7. text2pcap: Converting ASCII hexdumps to network captures ...................................... 173

C.8. idl2eth: Creating dissectors from Corba IDL files ...................................................... 176

C.8.1. What is it? ............................................................................................... 176

C.8.2. Why do this? ............................................................................................176

C.8.3. How to use idl2eth .....................................................................................176

C.8.4. TODO ..................................................................................................... 177

C.8.5. Limitations ..............................................................................................178

C.8.6. Notes ......................................................................................................178

D. This Document's License (GPL) ........................................................................................ 180

vii

Preface

1. Foreword

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.

This document is part of an effort by the Ethereal team to improve the usability of Ethereal.

We hope that you find it useful, and look forward to your comments.

viii

Preface

2. Who should read this document?

The intended audience of this book is anyone using Ethereal.

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.

This book is not intended to explain network sniffing in general and it will not provide details about

specific network protocols. A lot of useful information regarding these topics can be found at the

Ethereal Wiki at http://wiki.ethereal.com

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.

ix

3. Acknowledgements

The authors would like to thank the whole Ethereal team for their assistance. In particular, the au-

thors would like to thank:

• Gerald Combs, for initiating the Ethereal project and funding to do this documentation.

• Guy Harris, for many helpful hints and a great deal of patience in reviewing this document.

• Gilbert Ramirez, for general encouragement and helpful hints along the way.

The authors would also like to thank the following people for their helpful feedback on this docu-

ment:

• Pat Eyler, for his suggestions on improving the example on generating a backtrace.

• Martin Regner, for his various suggestions and corrections.

• Graeme Hewson, for a lot of grammatical corrections.

Preface

The authors would like to acknowledge those man page and README authors for the ethereal

project from who sections of this document borrow heavily:

• Scott Renfro from whose mergecap man page Section C.6, “mergecap: Merging multiple cap-

ture files into one ” is derived.

• Ashok Narayanan from whose text2pcap man page Section C.7, “text2pcap: Converting ASCII

hexdumps to network captures ” is derived.

• Frank Singleton from whose README.idl2eth Section C.8, “idl2eth: Creating dissectors

from Corba IDL files ” is derived.

x

Preface

4. About this document

This book was originally developed by Richard Sharpe with funds provided from the Ethereal Fund.

It was updated by Ed Warnicke and more recently redesigned and updated by Ulf Lamping.

It is written in DocBook/XML.

You will find some specially marked parts in this book:

This is a warning!

You should pay attention to a warning, as otherwise data loss might occur.

This is a note!

A note will point you to common mistakes and things that might not be obvious.

This is a tip!

Tips will be helpful for your everyday work using Ethereal.

xi

Preface

5. Where to get the latest copy of this document?

The latest copy of this documentation can always be found at: http:/ / www.ethereal.com/ docs/

#usersguide.

xii

Preface

6. Providing feedback about this document

Should you have any feedback about this document, please send them to the authors through ethere-

al-dev[AT]ethereal.com.

xiii

Preface

xiv

Chapter 1. Introduction

1.1. What is Ethereal?

Ethereal is a network packet analyzer. A network packet analyzer will try to capture network pack-

ets and tries to display that packet data as detailed as possible.

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).

In the past, such tools were either very expensive, proprietary, or both. However, with the advent of

Ethereal, all that has changed.

Ethereal is perhaps one of the best open source packet analyzers available today.

1.1.1. Some intended purposes

Here are some examples people use Ethereal for:

• network administrators use it to troubleshoot network problems

• network security engineers use it to examine security problems

• developers use it to debug protocol implementations

• people use it to learn network protocol internals

Beside these examples, Ethereal can be helpful in many other situations too.

1.1.2. Features

The following are some of the many features Ethereal provides:

• Available for UNIX and Windows.

• Capture live packet data from a network interface.

• Display packets with very detailed protocol information.

• Open and Save packet data captured.

• Import and Export packet data from and to a lot of other capture programs.

• Filter packets on many criteria.

• Search for packets on many criteria.

• Colorize packet display based on filters.

• Create various statistics.

• ... and a lot more!

However, to really appreciate its power, you have to start using it.

Figure 1.1, “ Ethereal captures packets and allows you to examine their content. ” shows Ethereal

having captured some packets and waiting for you to examine them.

1

Introduction

Figure 1.1. Ethereal captures packets and allows you to examine their content.

1.1.3. Live capture from many different network media

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: http://www.ethereal.com/media.html.

1.1.4. Import files from many other capture programs

Ethereal can open packets captured from a large number of other capture programs. For a list of in-

put formats see Section 5.2.2, “Input File Formats”.

1.1.5. Export files for many other capture programs

Ethereal can save packets captured in a large number of formats of other capture programs. For a list

of output formats see Section 5.3.2, “Output File Formats”.

1.1.6. Many protocol decoders

There are protocol decoders (or dissectors, as they are known in Ethereal) for a great many proto-

cols: see Appendix B, Protocols and Protocol Fields.

1.1.7. Open Source Software

Ethereal is an open source software project, and is released under the GNU General Public Licence

(GPL). You can freely use Ethereal on any number of computers you like, without worrying about

2

Introduction

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!

1.1.8. What Ethereal is not

Here are some things Ethereal does not provide:

• 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, Ether­eal might help you figure out what is really going on.

• Ethereal will not manipulate things on the network, it will only "measure" things from it. Ethere­al doesn't send packets on the network or do other active things (except for name resolutions, but
even that can be disabled).

3

Introduction

1.2. Platforms Ethereal runs on

Ethereal currently runs on most UNIX platforms and various Windows platforms. It requires GTK+,
GLib, libpcap and some other libraries in order to run.

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 ethereal-dev[AT]ethereal.com.

Binary packages are available for at least the following platforms:

1.2.1. Unix

• Apple Mac OS X

• BeOS

• FreeBSD

• HP-UX

• IBM AIX

• NetBSD

• OpenBSD

• SCO UnixWare/OpenUnix

• SGI Irix

• Sun Solaris/Intel

• Sun Solaris/Sparc

• Tru64 UNIX (formerly Digital UNIX)

1.2.2. Linux

• Debian GNU/Linux

• Gentoo Linux

• IBM S/390 Linux (Red Hat)

• Mandrake Linux

• PLD Linux

• Red Hat Linux

• Rock Linux

• Slackware Linux

• Suse Linux

4

1.2.3. Microsoft Windows

Maintained:

• Windows Server 2003 / XP / 2000 / NT 4.0

• Windows Me / 98

Unsupported/Unmaintained (because lack of required libraries):

• Windows CE

• Windows NT / XP Embedded

• Windows 95 is no longer actively maintained by WinPcap, but still may work perfectly

No experiences (fresh versions):

• Windows XP 64-bit Edition

Introduction

• Windows Vista (aka Longhorn)

Please provide your experiences about these fresh versions to: ethereal-dev[AT]ethereal.com.

5

Introduction

1.3. Where to get Ethereal?

You can get the latest copy of the program from the Ethereal website: ht-

tp://www.ethereal.com/download.html. The website allows you to choose from among several mir-

rors for downloading.
A new Ethereal version will typically become available every 4-8 weeks.
If you want to be notified about new Ethereal releases, you should subscribe to the ethereal-an-

nounce mailing list. You will find more details in Section 1.7.4, “Mailing Lists”.

6

Introduction

1.4. A rose by any other name

William Shakespeare wrote: "A rose by any other name would smell as sweet." And so it is with
Ethereal, as there appears to be two different ways that people pronounce the name.

Some people pronounce it ether-real, while others pronounce it e-the-real, as in ghostly, insubstan­tial, etc.

You are welcome to call it what you like, as long as you find it useful. The FAQ gives the official
pronunciation as "e-the-real".

7

Introduction

1.5. A brief history of Ethereal

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.

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.

Not long after that Gilbert Ramirez saw its potential and contributed a low-level dissector to it.
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.
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.

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.

8

Introduction

1.6. Development and maintenance of Ethereal

Ethereal was initially developed by Gerald Combs. Ongoing development and maintenance of Eth­ereal is handled by the Ethereal team, a loose group of individuals who fix bugs and provide new
functionality.

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 authors page on the Ethereal
web site.

Ethereal is an open source software project, and is released under the GNU General Public Licence
(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.

You gain three benefits by contributing your improvements back to the community:

• 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.

• 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.

• 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.

The Ethereal source code and binary kits for some platforms are all available on the download page
of the Ethereal website: http://www.ethereal.com/download.html.

9

Introduction

1.7. Reporting problems and getting help

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).

1.7.1. Website

You will find lot's of useful information on the Ethereal homepage at http://www.ethereal.com.

1.7.2. Wiki

The Ethereal Wiki at http://wiki.ethereal.com provides a wide range of information related to Ether­eal and packet capturing in general. You will find a lot of information not part of this user's guide.
For example, there is an explanation how to capture on a switched network, an ongoing effort to
build a protocol reference and a lot more.

And best of all, if you would like to contribute your knowledge on a specific topic (maybe a net­work protocol you know well), you can edit the wiki pages by simply using your webbrowser.

1.7.3. FAQ

The "Frequently Asked Questions" will list often asked questions and the corresponding answers.

Read the FAQ!

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).

You will find the FAQ inside Ethereal by clicking the menu item Help/Contents and selecting the
FAQ page in the upcoming dialog.

An online version is available at the ethereal website: http://www.ethereal.com/faq.html. You might
prefer this online version, as it's typically more up to date and the HTML format is easier to use.

1.7.4. Mailing Lists

There are several mailing lists of specific Ethereal topics available:

ethereal-announce This mailing list will inform you about new program releases, which

ethereal-users This list is for users of Ethereal. People post questions about building

ethereal-dev This list is for Ethereal developers. If you want to start developing a

usually appear about every 4-8 weeks.

and using Ethereal, others (hopefully) provide answers.

protocol dissector, join this list.

You can subscribe to each of these lists from the Ethereal web site: http://www.ethereal.com.
Simply select the mailing lists link on the left hand side of the site. The lists are archived at the Eth­ereal web site as well.

Tip!

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.

10

Introduction

1.7.5. Reporting Problems

Note!

Before reporting any problems, please make sure you have installed the latest version
of Ethereal.

When reporting problems with Ethereal, it is helpful if you supply the following information:

1. The version number of Ethereal and the dependent libraries linked with it, eg GTK+, etc. You

can obtain this with the command ethereal -v.

2. Information about the platform you run Ethereal on.

3. A detailed description of your problem.

4. If you get an error/warning message, copy the text of that message (and also a few lines before

and after it, if there are some), so others may find the place where things go wrong. Please don't
give something like: "I get a warning while doing x" as this won't give a good idea where to
look at.

Don't send large files!

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.

Don't send confidential information!

If you send captured data to the mailing lists, be sure they don't contain any sensitive
or confidential information like passwords or such.

1.7.6. Reporting Crashes on UNIX/Linux platforms

When reporting crashes with Ethereal, it is helpful if you supply the traceback information (besides
the information mentioned in "Reporting Problems").

You can obtain this traceback information with the following commands:

$ gdb `whereis ethereal | cut -f2 -d: | cut -d' ' -f2` core >& bt.txt
backtrace
^D
$

Note

Type the characters in the first line verbatim! Those are back-tics there!

Note

11

Introduction

backtrace is a gdb 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 gdb to exit. This will leave you with a file called
bt.txt in the current directory. Include the file with your bug report.

Note

If you do not have gdb available, you will have to check out your operating system's
debugger.

You should mail the traceback to the ethereal-dev[AT]ethereal.com mailing list.

1.7.7. Reporting Crashes on Windows platforms

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.

12

Introduction

13

Chapter 2. Building and Installing Ethereal

2.1. Introduction

As with all things, there must be a beginning, and so it is with Ethereal. To use Ethereal, you must:

• Obtain a binary package for your operating system, or

• Obtain the source and build Ethereal for your operating system.

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.

This chapter shows you how to obtain source and binary packages, and how to build Ethereal from
source, should you choose to do so.

The following are the general steps you would use:

1. Download the relevant package for your needs, e.g. source or binary distribution.

2. Build the source into a binary, if you have downloaded the source.

This may involve building and/or installing other necessary packages.

3. Install the binaries into their final destinations.

14

Building and Installing Ethereal

2.2. Obtaining the source and binary distributions

You can obtain both source and binary distributions from the Ethereal web site: ht-

tp://www.ethereal.com. 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.

Download all required files!

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.

Once you have downloaded the relevant files, you can go on to the next step.

Note!

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.

For this reason, you might want to pull down the source distribution and build it, as the
process is relatively simple.

15

Building and Installing Ethereal

2.3. Before you build Ethereal under UNIX

Before you build Ethereal from sources, or install a binary package, you must ensure that you have
the following other packages installed:

• GTK+, The GIMP Tool Kit.
You will also need Glib. Both can be obtained from www.gtk.org

• libpcap, the packet capture software that Ethereal uses.
You can obtain libpcap from www.tcpdump.org

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.

If you have downloaded the source for GTK+, the instructions shown in Example 2.1, “Building

GTK+ from source” may provide some help in building it:

Example 2.1. Building GTK+ from source

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>

Note!

You may need to change the version number of gtk+ in Example 2.1, “Building GTK+

from source” 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, tar xvf - will
show you the name of the directory you should change to.

Note!

If you use Linux, or have GNU tar installed, you can use tar zxvf gtk+-1.2.10.tar.gz.
It is also possible to use gunzip -c or gzcat rather than gzip -dc on many UNIX sys­tems.

Note!

If you downloaded gtk+ or any other tar file using Windows, you may find your file
called gtk+-1_2_8_tar.gz.

You should consult the GTK+ web site if any errors occur in carrying out the instructions in Ex-

ample 2.1, “Building GTK+ from source”.

If you have downloaded the source to libpcap, the general instructions shown in Example 2.2,

16