# &app; Manual

## Introduction

&appname; 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, slip, wlan devices plus several encapsulated packet types. It can filter traffic to be shown, and can read traffic from a file as well as live from the network.

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

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

&app; supports several command line options to simplify monitoring. Please refer to the &appname; unix manual page, &app;(1).

## Using &appname;

&app; 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

To monitor a live network you need to run &app; with root permissions. If you are not the administrator of the machine you will ony be able to analyze previously generated capture files.

As with any application, running &app; as root can be a security risk if some malicious traffic can trigger an unwanted behaviour.

While at this time no such bugs are known, exercise a little care.

Starting &app; opens the Main window (see screenshot).

By default, &app; 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 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 or in the All Protocols dialog.

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, &appname; offers you the possibility of displaying stastistics for many of the elements involved. Read on to learn how.

#### &appname; Main Window

&appname; Main Window screenshot

### Modes

Modes control how &app; captures, decodes and displays network packets. Node identification also depend on the current mode, thus changing mode requires restarting the capture.

Link Layer

- Link Layer mode focuses on traffic at link layer (e.g. Ethernet) level. Nodes are identified by their link layer address, highlighting local paths.

  In this mode traffic coming from an external network across a router is shown as originating at the router. Conversely, packets headed outside are shown as consumed by the router.

  To convert MAC addresses to machine names, &app; reads uses the /etc/ethers file.

  Default filter: none

IP

- The default mode, focusing on traffic at IP level or above. Nodes are identified by their IP address, if available.

  Unless directly addressed, routers are ignored, showing the final packet destination.

  The default filter expression is 'ip or ip6', discarding all non IP packets. Remove the filter to see non-IP traffic (e.g. ARP queries)

  Due to pcap limitations, when filtering while capturing VLAN-tagged packets, your filter must start with 'vlan' (e.g. 'vlan and (ip or ip6)' ) and all traffic must be tagged, otherwise the filter will not work.

TCP

- In this mode a node represents an (host, port) pair, with node labels shown as "name:port".

  Since the display becomes quickly crowded, this mode is best suited for analyzing a small number of hosts, perhaps by restricting the capture scope with a filter.

  The default filter expression for TCP mode is 'tcp', capturing only TCP packets. Removing the filter usually doesn't make much sense, but you can change it to 'tcp or udp' to see both TCP and UDP traffic.

  Due to pcap limitations, when filtering while capturing VLAN-tagged packets, your filter must start with 'vlan' (e.g. 'vlan and tcp') and all traffic must be tagged, otherwise the filter will not work.

## Toolbar

The toolbar provides access to several commonly used routines.

Start

- Starts capturing on the selected live interface.

Next

- Active only when replaying a capture file, when pressed fast forwards to the next packet, skipping any delay. Useful for dealing with long pauses in captured data.

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 &appname; running for several hours.

Pref.

- Opens the Preferences dialog.

Prot.

- Opens the Protocols detail window.

Nodes

- Opens the All Nodes detail window.

### &appname; Toolbar

&appname; 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.

    Capture files often contain lengthy sections without traffic. Here the command-line option --max-delay or the Next button may be useful to avoid staring for hours to an empty display. Conversely, --min-delay can help analyze many short lived connections.

  - Export creates an xml with a snapshot of current nodes and their statistics. A sample output file can be found in appendix-a.

    &app; can automatically export to user-chosen files with two command line options, `--final-export` and `--signal-export`. The first writes to file at end of a replay, the second dumps when receiving signal USR1.

  - Preferences opens the Preferences dialog.

  - Quit quits the application.

Capture

- This menu contains:

  - Mode opens a submenu governing the operating mode.

    - Alt-L Link Layer Selects Link Layer mode.

    - Alt-I IP Selects IP mode.

    - Alt-T TCP Selects TCP mode.

  - Interfaces opens a submenu to select the capture interface.

  - Start begins capturing on the selected live interface.

  - Next when pressed fast forwards to the next packet, skipping any delay. Useful for dealing with long pauses in captured data. Active only during replay.

  - 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 &appname; running for several hours.

View

- This menu contains:

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

  - Nodes opens the All Nodes dialog, which allows you see all known nodes with summary statistics.

  - Toolbar toggles the toolbar.

    Legend toggles the protocol legend.

    Statusbar toggles the Status bar.

Help

- This menu contains:

  - About Opens the About dialog which shows basic information about &app;, such as release number, or the author's names.

## 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. The third row shows average packet size.

A protocol table depicting data on all protocol traversing the chosen node is also displayed. See the All Protocols 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. The third row shows average packet sizes.

A protocol table depicting data on all protocol traversing the chosen link is also displayed. See the All Protocols 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

## All Protocols dialog

The Protocols dialog shows global traffic statistics for active (i.e. not expired) protocols. 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, or disabled by deselecting it in the Columns menu.

Available statistics are:

- Protocol color

- Protocol name. For TCP/UDP traffic, the services file is searched for a matching entry.

- Protocol port (TCP/UDP traffic only).

  &app; assigns the same port to all nodes in a packet using the following heuristic:

  1. if only one port of the two matches is mapped to a color, that entry is used. This way you can override automatic port assignement.

  2. if both ports of packet are mapped, the minor one is choosen.

  3. if only one port of the two matches an entry of the services file, that entry is used.

  4. if both ports of packet match, the minor one is choosen.

  5. if no ports match a services file entry, the minor one is chosen. The packet is labelled "unknown traffic" and processed as such (see "Group unknown ports" in group-unknown).

- Inst Traffic shows the (moving average of) active traffic.

- Accum Traffic shows the accumulated traffic.

- Avg Size is the average packet size computed on the total traffic seen.

- Last Heard reports when the last packet was seen.

- Packets is the total number of packets.

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

### Protocol detail dialog

All Protocols dialog screenshot

## All Nodes dialog

The Nodes dialog shows global traffic statistics for all known (i.e. not expired) nodes. Expiration is controlled by the Node 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.

This dialog lists all known nodes, even those not shown on the diagram because their Diagram timeout is expired. A node is fully expired and &app; forgets it only when all three timeouts (Diagram, Traffic Statistics, Protocol Statistics) are expired.

### All Nodes dialog

All Nodes dialog screenshot

## Preferences

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

- Diagram

- Colors

- Timings

Any change you make will be applied immediately. When satisfied, click on OK to close the Properties dialog. The Save saves current settings (to ~/.gnome2/&appname;).

To abort the changes and return to previous values, click the Cancel button.

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

  Protocol level attribution can be confused by encapsulation. For instance, when an Ethernet packet containing IP traffic is encapsulated by an LLC-SNAP header, IP data might be incorrectly flagged as ISO level 4 or 5.

  The most safe settings is 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.

    In this context, "istantaneous" means traffic averaged over the "Averaging Time Period".

  - Instant. traffic (Inbound)

    Size depends on instantenous inbound traffic.

  - Instant. traffic (Outbound)

    Size depends on instantaneous outbound traffic.

  - Accum. traffic (In+Out)

    Size depends on the total traffic accumulated on node.

  - Accum. traffic (Inbound)

    Size depends on accumulated inbound traffic.

  - Accum. traffic (Outbound)

    Size depends 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.

  - Square Root

    Uses the square root of input variable.

  Default: Linear.

Node Radius Multiplier

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

Link Width - Node Radius Ratio

- This slider specifies the ratio between node and link sizes.

  Default: 1.

Capture filter

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

  Default: ip

Node Label Font

- Selects the font used for node labels.

  Default: Sans 8 Pts..

Node Label Color

- Selects the color used for node labels.

  Default: yellow.

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". In unchecked, those ports are shown as "UDP-nnnn" or "TCP-nnnn", where nnnn is the port number.

  &app; assigns the same port to all nodes in a packet using the following heuristic:

  1. if only one port of the two matches an entry of the services file, that entry is used.

  2. if both ports of packet match, the minor one is choosen.

  3. if no ports match an entry, the minor one is chosen. The packet is labelled "unknown traffic" and processed as such.

  Default: checked.

Name resolution

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

  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 one or more protocols.

  The Color column shows the color

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

  &appname; 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 items without an assigned protocol. If all entries have an assigned protocol unmapped traffic will be shown as gray.

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.

Change color

- A dialog will open to choose a new color for the selected row.

Edit protocols

- Opens a dialog where the current row protocols can be edited. A row can contain multiple protocols, separated by a comma.

  #### Protocol edit dialog

#### Colors preferences tab

Colors preferences tab screenshot

### Timings

The timings tab contains all time-related settings of &appname;.

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

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

Due to pcap limitations, VLAN-tagged packets are visible only if the filter expression starts with 'vlan' and in this case only VLAN-tagged traffic will be shown.

OSI level attribution can be confused by encapsulation. For instance, when an Ethernet packet containing IP traffic is encapsulated by an LLC-SNAP header, IP data might be incorrectly flagged as ISO level 4 or 5.

Most NFS traffic will show up as UDP_FRAGMENT or just RPC

Older distributions, (e.g. CentOS 5, or RHEL 5) do not support PPI encapsulation.

## XML export file format

This section presents &app; XML export file format followed by a detailed analysis.

At this time &app; exports only node informations. Future releases might export also link data.

This example shows a file containing only a single, simple, node. A real file will contain many nodes, possibly with more involved <protocol> subtags. The general structure remains the same, however.

    <?xml version="1.0"?>
    <!-- traffic data in bytes. last_heard in seconds from dump time -->
    <etherape>
      <header>
        <capture_device>eth0</capture_device>
        <timestamp>2011-02-26 10:33:27 +0100</timestamp>
      </header>
      <nodes>
        <node>
          <name>
            <id>
              <IP>10.0.0.98</IP>
            </id>
            <resolved_name>floss.rulez.example.net</resolved_name>
            <numeric_name>10.0.0.98</numeric_name>
          </name>
          <traffic_stats>
            <active_packets>12</active_packets>
            <in>
              <stats>
                <avg>1080</avg>
                <total>1027</total>
                <avg_size>102</avg_size>
                <packets>10</packets>
                <last_heard>0.357600</last_heard>
              </stats>
            </in>
            <out>
              <stats>
                <avg>34416</avg>
                <total>14456</total>
                <avg_size>1205</avg_size>
                <packets>12</packets>
                <last_heard>0.000000</last_heard>
              </stats>
            </out>
            <tot>
              <stats>
                <avg>35496</avg>
                <total>15483</total>
                <avg_size>704</avg_size>
                <packets>22</packets>
                <last_heard>0.000000</last_heard>
              </stats>
            </tot>
            <protocols>
              <protocol>
                <level>1</level>
                <key>ETH_II</key>
                <stats>
                  <avg>55948</avg>
                  <total>14049</total>
                  <avg_size>669</avg_size>
                  <packets>21</packets>
                  <last_heard>0.174299</last_heard>
                </stats>
                <name>
                  <id>
                    <link>fe:ff:20:00:01:00</link>
                  </id>
                  <numeric_name>fe:ff:20:00:01:00</numeric_name>
                  <accumulated>14049</accumulated>
                </name>
              </protocol>
              <protocol>
                <level>2</level>
                <key>IP</key>
                <stats>
                  <avg>55948</avg>
                  <total>14049</total>
                  <avg_size>669</avg_size>
                  <packets>21</packets>
                  <last_heard>0.174299</last_heard>
                </stats>
                <name>
                  <id>
                    <IP>10.0.0.98</IP>
                  </id>
                  <resolved_name>floss.rulez.example.net</resolved_name>
                  <numeric_name>10.0.0.98</numeric_name>
                  <accumulated>14049</accumulated>
                </name>
              </protocol>
              <protocol>
                <level>3</level>
                <key>TCP</key>
                <stats>
                  <avg>55948</avg>
                  <total>14049</total>
                  <avg_size>669</avg_size>
                  <packets>21</packets>
                  <last_heard>0.174299</last_heard>
                </stats>
              </protocol>
              <protocol>
                <level>4</level>
                <key>WWW</key>
                <stats>
                  <avg>55948</avg>
                  <total>14049</total>
                  <avg_size>669</avg_size>
                  <packets>21</packets>
                  <last_heard>0.174299</last_heard>
                </stats>
              </protocol>
            </protocols>
          </traffic_stats>
        </node>
      </nodes>
    </etherape>

The export file begins with an header (lines 5-9) containing the file replayed (tag <capture_file>, not shown) or the capture device (tag <capture_device>, line 5), followed by the export timestamp.

Node information are, perhaps unsurprisingly, enclosed by <node> tags (lines 9-115). A node is composed by an identifying header, <name> (lines 10-16) followed by traffic statistics, enclosed by <traffic_stats> (lines 17-107).

Lines 10-16 contain the primary node identifier, i.e. the name/address displayed by &app;. In this example is the IPv4 address 10.0.0.4, along its resolved name.

While only one <name> can be displayed, a node usually has multiple identities: an Ethernet MAC address, an IP one, perhaps a NETBIOS name. Every identity has a matching <name> element; see lines 57-63 and 74-82.

A <name> is identified by its <id> i.e. its address, which can be of type IP (an IPv4 dotted decimal address), IPv6 or 'link', a link-level, colon separated, list of octets (e.g. the Ethernet MAC address). You see an example of the latter in lines 58-60.

<numeric_name> and <resolved_name> are the high level equivalent of <id>; <accumulated> is the total bytes of traffic related with the name. &app; uses this statistic to choose between multiple names.

Traffic statistics (lines 17-107) give a summary of node traffic: first, the number of active packets (line 18), i.e. the packets received during the 'Node traffic statistics' interval (see etherape-prefs-timings). <in> record incoming traffic, <out> outgoing and <tot> the total bytes seen. The <protocols> element reports traffic broken down by protocol.

<stats> elements are:

- <avg> is the moving average of active packets (see "Averaging Time", etherape-prefs-timings), in bytes. Shown as 'Instantaneous' traffic in nodedlg

- <total> is the accumulated traffic seen.

- <avg_size> is the average packet size.

- <packets> is the number of packets received.

- <last_heard> is the distance in seconds between time of exporting and the last packet seen. I.e. 2.000100 means 2 seconds and 100 microseconds ago.

<protocol> elements carry per protocol breakdown of node statistics. A packet might affect multiple protocols: an HTTP request over Ethernet is recorded by protocols "WWW", "TCP", "IP" and "ETH_II", while an Ethernet broadcast is seen only as "ETH_II".

Here <level> roughly equates to the OSI level, but multiple encapsulation can confuse the engine and introduce additional levels. A protocol level 2 is always lower than one of level 3.

<key> is a mnemonic identifier of the protocol; for TCP/UDP ports is taken from the services file, if available.

There can be multiple entries with the same level (e.g. HTTP and IMAP). Only the combination of level and key is unique.

## Authors

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

To find more information about &app;, please visit the &app; 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