# EtherApe Manual

## Introduction

EtherApe is a graphical network monitor for Unix modeled after etherman. Featuring ether, ip and tcp modes, it displays network activity graphically. Hosts and links change in size with traffic. Protocols are color coded. It supports ethernet, fddi, ppp and slip devices. It can filter traffic to be shown, and can read traffic from a file as well as live from the network.

EtherApe is also a tool for gathering network statistics, and the data can be presented in a number of different ways.

To run EtherApe, select Applications EtherApe from the Main Menu, or type `etherape` on the command line.

## Using EtherApe

EtherApe can be used to have an overview of traffic conditions in your network. It is a great tool to easily pinpoint who is consuming the most bandwith, or to check which computers are actually talking to some others.

### Quick Start

Most of the time you will want to run EtherApe with root permissions in order to monitor a live network. If you are not the administrator of the machine running EtherApe, you will ony be able to analyze previously generated capture files, generated by someone else.

Starting EtherApe opens the Main window (see screenshot).

By default, EtherApe will try to open the default network interface for capture in IP mode, and will display a diagram of network traffic right away.

Every computer currently taking part in a conversation in the network will be represented as a circle (a node) in the diagram, with its name displayed on top of it. The fact that two computers are communicating with each other is represented with a line between those two nodes (a link).

You will notice that both nodes and links vary with time in color and size. Size is used to represent the amount of traffic: The bigger a node is, the more traffic it is dumping into the network. The wider a link is, the more data is flowing in that particular between those two nodes.

Color, on the other hand, is used to represent the protocol being used the most by a link or a node. You will find a legend for what a particular color means in the left side of the main window.

Look closely and you will notice that in fact links are not lines between nodes. Rather, every direction of communication is represented by a triangle. Packets go from the shorter side to the opposite vertex. Since computers usally talk back, there will usually be two such triangles between two nodes, the base of each representing how much each node is contributing to the conversation.

You don't need to know much more if you just want to have a simple look at your network. Nevertheless, there are many settings that you can use to configure what exactly will appear in the diagram, and you will have to understand how this settings affect the program to have a proper comprehension of the meaning of the display.

Besides, EtherApe offers you the possibility of displaying stastistics for many of the elements involved. Read on to learn how.

#### EtherApe Main Window

Etherape Main Window screenshot

### Toolbar

The toolbar provides access to several commonly used routines.

Start

- Starts capturing on the selected live interface.

Pause

- Pauses capture, freezing both the diagram and any detail window.

Stop

- Stops the capture, clearing diagram and all traffic statistics. Closes also all detail windows .

  Everytime a capture is stopped, all statistics gathered up to that time will be deleted from memory. Think about it when you have left EtherApe running for several hours.

Preferences

- Opens the Preferences dialog.

Protocols

- Opens the Protocols detail window.

#### EtherApe Toolbar

Etherape toolbar screenshot

### Menus

The menu bar, located at the top of the Main Window, contains the following menus:

File

- This menu contains:

  - Ctrl-O Open opens an external capture file. If you want to capture on a live interface, see the Capture menu.

  - Preferences opens the Preferences dialog.

  - Quit quits the application.

Capture

- This menu contains:

  - Mode opens a submenu governing the capture mode.

  - Interfaces opens a submenu to select the capture interface.

  - Start begins capturing on the selected live interface.

  - Pause temporarily halts the capture, freezing both the diagram and any detail window.

  - Stop terminates the capture, clearing diagram and traffic statistics. Closes also all detail windows .

    Everytime a capture is stopped, all statistics gathered up to that time will be deleted from memory. Think about it when you have left EtherApe running for several hours.

View

- This menu contains:

  - Protocols opens the Protocols dialog, which allows you see global traffic statistics per protocol.

  - Toolbar toggles the toolbar.

    Legend toggles the protocol legend.

    Statusbar toggles the Status bar.

Help

- This menu contains:

  - About This opens the About dialog which shows basic information about EtherApe, such as the author's name.

## Node detail dialog

Double-clicking on a node opens a detail dialog wich shows realtime traffic statistics for the chosen node.

Averaged realtime traffic is shown in the "Istantaneous" row, while the "Accumulated" one displays long term statistics.

A protocol table depicting data on all protocol traversing the chosen node is also displayed. See the Protocol detail dialog entry for additional information.

Only active protocols matching the "Protocol Stack Level" preference settings will be displayed.

### Node detail dialog

Node detail dialog screenshot

## Link detail dialog

Double-clicking on a link opens a detail dialog wich shows realtime traffic statistics for the chosen link.

Averaged realtime traffic is shown in the "Istantaneous" row, while the "Accumulated" one displays long term statistics.

A protocol table depicting data on all protocol traversing the chosen link is also displayed. See the Protocol detail dialog entry for additional information.

Only active protocols matching the "Protocol Stack Level" preference settings will be displayed.

### Link detail dialog

Link detail dialog screenshot

## Protocol detail dialog

The protocol detail dialog shows global traffic statistics for active (i.e. not expired) protocolos. Expiration is controlled by the Global Protocol Timeouts preference section.

Double clicking on a column name orders entries by that column data or reverses the sorting order. A small arrow after the chosen column name shows the sorting order (in the screenshot, entries are ordered by name).

A column can also be dragged, changing its position in the table. To disable a column deselect it in the Columns menu.

Only those protocols matching the "Protocol Stack Level" preference settings will be displayed.

### Protocol detail dialog

Protocol detail dialog screenshot

## Settings

To change the application settings, select File Preferences... . The Preferences dialog contains the following tabbed sections:

- Diagram

- Colors

- Timings

After you have made all the changes you want, click on OK to apply the changes and close the Properties dialog. The Save saves current settings (to ~/.gnome2/EtherApe).

### Diagram

The diagram tab contains many settings related to the traffic display.

Protocol Stack Level

- Use this drop-down list box to specify the level of the OSI stack to use when displaying protocols. Select one of the following options:

  - Topmost recognized protocol

    For every packet, chooses the highest level protocol detected.

  - Level 2 (Eg: ETHII)

    Shows only OSI level 2 informations. For example ETHII or FDDI

  - Level 3 (Eg: IP)

    Shows only OSI level 3 protocols, like IP or IPX

  - Level 4 (Eg: TCP)

    Shows only OSI level 4 protocols, tipically TCP, UDP and ICMP

  - Level 5 (Eg: HTTP)

    Shows application level protocols, like HTTP, POP3, etc

  Default: Topmost recognized protocol.

Node Size Variable

- Use this drop-down list box to specify wich variable governs node and link sizes. Select one of the following options:

  - Instant. traffic (In+Out)

    Size depends on the instantaneous traffic on node.

  - Instant. traffic (Inbound)

    Size depends only on instantenous inbound traffic.

  - Instant. traffic (Outbound)

    Size depends only on instantaneous outbound traffic.

  - Accum. traffic (In+Out)

    Size depends on the total traffic accumulated on node.

  - Accum. traffic (Inbound)

    Size depends only on accumulated inbound traffic.

  - Accum. traffic (Outbound)

    Size depends only on accumulated outbound traffic.

  Default: Instant. traffic (Outbound).

Size Mode

- Use this drop-down list box to specify how to weight the value of the Node Size Variable. Select one of the following options:

  - Linear

    Uses directly the input value.

  - Logarithmic

    Uses the decimal logarithm of input variable.

  - Quadratic

    Uses the square root of input variable.

  Default: Linear.

Node Radius Multiplier

- This slider specifies the scaling multiplier to apply to node sizes.

Link Radius Multiplier

- This slider specifies the scaling multiplier to apply to link sizes.

Capture filter

- This drop-down combo box specifies the capture filter to use using the standard pcap syntax.

  Default: ip

Font

- Opens the font selection dialog to select the main application font.

Hide node names

- If checked, doesn't show the node names.

  Default: unchecked.

Group unknown ports

- If checked, all traffic belonging to ports not specified in the services file is accumulated under "UDP-unknown" and "TCP-unknown".

  Default: checked.

Name resolution

- If checked, enables name resolution. If unchecked, show only numeric addresses (like the -b command line option).

  Default: unchecked.

Node Anti Aliasing

- Enables node antialiasing. On slower computers, it could be unchecked to save a few CPU cycles.

  Default: checked.

#### Diagram preferences tab

Diagram preferences tab screenshot

### Colors

The colors tab assigns colors to protocols.

Color-Protocol matching table

- This list box lists available colors and optionally maps a specified color to a protocol.

  The Color column shows the color and its RGB hexadecimal id (#rrggbb)

  A color could appear in more rows, to allow protocol grouping by color (e.g. show FTP and FTP-PASSIVE as cyan).

  EtherApe will use only the colors specified in this list. If the list is empty, all diagrams will be gray.

  The mapping of colors to protocols works as follows:

  - A protocol wich name appears in a Protocol column, will be drawn in the corresponding row color. As an example, in the dialog screenshot, all DOMAIN traffic is drawn in blue.

  - A protocol not appearing in the list will have a color assigned casually from the list. If the Cycle assigned colors checkbox is selected, all listed colors will be considered. Otherwise, only those without an assigned protocol will be used.

Add color

- Adds a new row to the list. A dialog will open to select the actual color value.

Remove color

- Removes the selected row from the list.

Edit protocols

- Opens a dialog where the current row protocol can be edited

  #### Protocol edit dialog

Fade colors

- When checked, colors fade to black when there is no traffic.

  Default: checked

Cycle assigned colors

- If checked, unmapped protocol can use all colors.

  Default: unchecked

#### Colors preferences tab

Colors preferences tab screenshot

### Timings

The timings tab contains all time-related settings of EtherApe.

Diagram Refresh Period (ms)

- Minimum time (in milliseconds) to wait before refreshing the diagram. Smaller values increase the frequency of updates, making the graph smoother, but with increased CPU usage.

Averaging Time (ms)

- Traffic average period in milliseconds. Smaller values follow more closely the instantaneous traffic, while higher settings smooth the diagram. Averages need packet data, so an higher averaging time means also higher memory consumption.

Node Timeouts (ms)

- This section aggregates all node timeout settings.

  Diagram

- After this time without traffic, the node is removed from diagram. Node data are still held in memory until the Traffic timeout expires, so if new traffic comes accumulated statistics are still valid. Zero disables the timer (i.e. a node never expires).

Traffic

- After this time without traffic, the node is removed from memory, clearing all statistics. A zero value disables the timeout.

Protocol Info

- After this time without traffic on a protocol, its statistics are removed from the node. A zero value disables the timeout.

Link Timeouts (ms)

- This section aggregates all link timeout settings.

  Diagram

- After this time without traffic, the link is removed from diagram. Link data are still held in memory until the Traffic timeout expires, so if new traffic comes accumulated statistics are still valid. Zero disables the timer (i.e. a link never expires).

Traffic

- After this time without traffic, the link is removed from memory, clearing all statistics. A zero value disables the timeout.

Protocol Info

- After this time without traffic on a protocol, its statistics are removed from the link. A zero value disables the timeout.

Global Protocol Timeouts (ms)

- This section aggregates all timeout settings related to the global protocol statistics.

  Traffic

- After this time without traffic, the protocol is removed from memory, clearing all statistics. A zero value disables the timeout.

#### Timings preferences tab

Timings preferences tab screenshot

## Known Bugs and Limitations

As default, only IP traffic is shown. To see other protocols use ethernet mode (-m ethernet)

Some libpcap versions have a bug for which a filter "ip" doesn't capture icmp traffic.

Most NFS traffic will show up as UDP_FRAGMENT or just RPC

## Authors

EtherApe was written by Juan Toledo ( toledo@users.sourceforge.net). Later releases by Riccardo Ghetta (bchiara@users.sourceforge.net).

To find more information about EtherApe, please visit the EtherApe Web page. Instructions for submitting bug reports can be found on-line.

## License

This program is free software; you can redistribute it and/or modify it under the terms of the "> GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

A copy of the GNU General Public License is included as an appendix to the GNOME Users Guide . You may also obtain a copy of the GNU General Public License from the Free Software Foundation by visiting their Web site or by writing to

    Free Software Foundation, Inc. 59 Temple
          Place - Suite 330 Boston, MA
          02111-1307 USA