Wireshark · Ethereal-dev: [Ethereal-dev] Please review: two new help pages

[Ulf Lamping <ulf.lamping@xxxxxx>]

Hi List!

I tried to write some more things for the help pages.

Could please someone have a review on the two pages:

getting_started.txt: for a very simple "first steps using Ethereal"
capturing.txt: for some explanation of the capturing options and some 
tips for doing high performance and long term capturings

As I'm not a native english speaker, this will be somewhat "ugly 
english" ahead ;-)

I might also have forgotten some important things, which should be added...

Regards, ULFL

Capturing
---------
This section will explain the capturing options and give hints what to do in some special cases.


Capture options
---------------
The capture options can be logically devided in the following categories:

-input
-filtering
-stop conditions
-storing
-display while capturing

Input options
-------------
-Interface: You have to choose, which interface (network card) should be used to capture packets from. Be sure to select the correct one, as it's a common mistake to select the wrong interface.

-Link-layer header type: XXX: could someone please explain this?

Filtering options
-----------------
-Limit each packet to xy bytes: Will limit the maximum size to be captured of each packet. This can be useful for example, when an error is known to be in the first 20 bytes of a packet, and the size of the resulting capture file should be reduced.

-Capture packets in promiscuous mode: Usually a network card will only capture the traffic to it's own network address. If you want to capture all traffic that the network card can "see", mark this option.

-Capture Filter: use a capture filter to reduce the amount of packets to be captured. See "Capture Filters" in this help for further information how to use it.

Stop condition options
----------------------
This three fields should be obvious, they will stop the capture process automatically, if one of the selected conditions is exceeded.

Storing options
---------------
-File: you can choose a file to instantly write packet data into it. If you don't enter something here, a temporary file will be used.

-Use ring buffer: Instead of using a single file, multiple ones will be created, the generated filename will contain a continuously increasing number and the start time of the capture. For example, if you choose "/foo.cap" in the "File" field, the files "/foo_00001_20040205110102.cap", "/foo_00002_20040205110102.cap", ... will be created.
This feature can be useful if you do long term capturing, as working with a single capture file of several GB usually isn't very fast.

Display while capturing options
-------------------------------
-Update List of packets in real time: Using this will show the captured packets immediately on the main screen.
Please note, that this will slow down capturing, so increased packet drops might appear.

-Automatic scrolling in live capture: This will scroll the "Packet List" automatically to the latest captured packet, when the "Update List of packets in real time" option is used.



High performance capturing
--------------------------
If you have lot's of traffic on your network and it's important to capture all the packets from it (at least as much as possible). Packets that could not be saved, while cpaturing from a network are known as packet drops.

The following rules might help you, to avoid packet drops:

a) Close all other programs, that might slow down your system, including virus scanner software, server processes, ...

b) Don't use the "Update List of packets in real time" option! This will update things on the 

c) It might be a good idea not to use a capture filter. This will depend on the task you have to do.
As a rule of thumb: if you want to see most of the packets and only filter some of the packets out, don't use a capture filter (you can use a display filter later). If you only want to capture some of the packets, it might be better to set a capture filter, as this will reduce the number of packets which has to be saved.

d) If you still get packet drops, it might be an idea to use a tool dedicated for packet capturing and only use Ethereal for displaying and analyzing packets.

Have a look at tethereal, the command line variant of ethereal, which is included in this package.
XXX: add a list of possibly useful standalone capture programs.



Long term capturing
-------------------
By "Long term capturing", it's meant to capture data from a network for several hours or even days. Long term capturing will usually result in huge capture files, being hundreds of MB's or even several GB's in size!

Before doing a long term capture, get familiar with the options to use for it, as you might not get what you desire. Doing a long term capture not getting the results needed, is usually wasting a lot of time ;-)

Rules of thumb for this task:
-Use the ring buffer feature when you expect very large capture files
-Don't use the "Update list of packets in real time" option
-Set an appropriate capture filter, when you are only interested in some special packets from the net

Getting started
---------------
This text will try to take you though the first steps of using Ethereal.


Display
-------
When you start Ethereal, you will see the program window vertically divided into the following parts:

-window title
-menu
-main toolbar
-packet list    (empty)
-packet details (empty)
-packet bytes   (empty)
-statusbar      (with filter toolbar)

As Ethereal has no packet data when started, most of the programs window is just empty.

Lot's of the features available at the menu will also be on the main toolbar.

First capture file
------------------
So the first thing you might want to do, is getting a capture file into the program.
This can be achieved by two methods:

-open an already existing capture file
-capture something from your own network

It might be easier to start with an example capture file from "http://www.ethereal.com/sample";,
before capturing your own data.

You can open a capture file through the menu "File->Open..." (or the toolbar).

Please note: the common file extension for capture files is ".cap" (or ".cap.gz" for gzipped ones).

After opening a capture file, you will hopefully see some more packet data on the screen :-)

Display fields
--------------
In the "packet list", you will see several columns with a packet number, timestamp(s), adresses and a protocol specific summary of that packet. Here you can select a packet to be shown in the "packet details" below.

In the "packet details", the details of the currently selected packet are shown. You can expand the tree nodes to get even more details about that packet.

The "packet bytes" will simply show all the packet data in a hexdump style. It will show the same packet as in the "packet details", only with a different representation.
When you select something in the "packet details", it will be highlighted in the "packet bytes" and vice versa.

All three display fields will have "their own" context menu, available by clicking the right mouse button inside the window.

How to analyze protocol specific network data itself is not in the scope of this text.

Display filters
---------------
You can reduce the number of packets shown (filter out the uninteresting ones), by setting a display filter. Please see "Display Filters" in this help dialog for further information how the display filters should be used.

Coloring Rules
--------------
The packet list can be colored, this means applying different colors for different packets. For example you could choose to have all http packets shown in red and all other TCP traffic shown in yellow.

Under "View->Coloring Rules..." you will see a list of color rules. This list is processed for every packet from top to bottom, until one of the rules do match (in that case the color settings of that rule are used for that packet). If no rule matches, the packet will not be colored at all.
Please note: setting lot's of color rules can slow down processing time a bit when showing huge capture files!

Other display things
--------------------
You can mark packets, to find back to packets of interest. 
You can set a time reference, if you are interested to see timings relative to a specific packet (e.g. get time differences relative to the start of some data transfer).
But remember: These settings will not be saved, so they are simply gone, when the capture file is closed.


Capture from the network
------------------------
Most likely you will now want to get some "real life" packet data captured from your own network interface.

So when opening the capture dialog with "Capture->Start...", you will see lot's of settings to choose. For a first try, just keep the default settings.

After click "Ok", the capture starts and a dialog shows up, telling the actual count of captured packets and some very basic packet statistics.

When you stop the capture, you will get the same screen as if you had opened a capture file from disk, using the "File->Open" command.

See the "Capturing" section of this help for further information about capturing.


Conclusion
----------
There are a lot more features than described here, have a look at the menu to see them all :-)

For more information about Ethereal, see: "http://www.ethereal.com";. You can get a user's guide and other useful information there.

Hope this helped you with the first steps of using Ethereal and that you will enjoy the program.