DaCoPAn user manual

Dacopan analyzer

  1. Configuration and installation
  2. Synopsis
  3. Description
  4. Options
  5. Protocol events file
  6. Examples
  7. Frequently Asked Questions

Dacopan animator

  1. Installation
  2. Screen parts
  3. Files
  4. Settings
  5. Controlling the animation
  6. Working with scenarios
  7. Frequently Asked Questions (FAQ)

DaCoPAn Analyzer

Configuration and installation

The DaCoPAn Analyzer is commonly distributed in a source package. To install the software:
  1. Unpack the archive.
  2. Run the configure script to check your system configuration.
  3. If the configure script complains about missing libraries or header files, install the required packages to satisfy the dependencies and run configure again. To compile the program you will need make, gcc ≥ 3.2 and libpcap ≥ 0.7.1 (earlier versions may work as well, but was not tested).
  4. Run make command to build the program.
  5. Run make install command to install the software.

The DaCoPAn Analyzer was only tested under Linux 2.4 and (most probably) will not compile for other operating systems.

For more details see the INSTALL file included with the source distribution.

Synopsis

dacopan-analyzer [OPTIONS] FILE1 FILE2

Description

The dacopan-analyzer is a part of DaCoPAn software.
The dacopan-analyzer program is used to read, merge and process data from tcpdump log files and store it in the protocol events file readable by the dacopan-animator.
All irrelevant information in log files are ignored. Each two corresponding packets are linked between log files (packet sent - packet received). For each non-linked packet dacopan-analyzer makes event "UNIT_DROPPED". All relevant information from log files are stored in the produced protocol events file.
Usually dacopan-analyzer is used only with -i flags. These flags are necessary for program and specifies used IP addresses.
The basic input data for dacopan-analyzer is two tcpdump log files which are created by tcpdump tool. The simple command for creating tcpdump logs is the following:
  • Host 192.168.0.1 - tcpdump -s 0 -w 1.dump host 192.168.0.2
  • Host 192.168.0.2 - tcpdump -s 0 -w 2.dump host 192.168.0.1
This examples also show tcpdump filter: the packets from other hosts does not include into produced log files.
The dacopan-analyzer has the following sequence of operations:
  1. First user sets necessary options (IP addresses, file names) and run program.
  2. dacopan-analyzer reads tcpdump log files and filters unnecessary data. Also using defined application port numbers defines application level.
  3. Each message contains in two log files: in one hand - message sent and in another hand - message received. This parts are calls events. dacopan-analyzer build links between this events. Also dacopan-analyzer merges all events into one sequence.
  4. The next step is split sequence between flows. Each flow is a quantity of messages between fixed ports. In this step dacopan-analyzer build events for all levels, defragments messages, makes "UNIT_DROPPED" events and calculates variables.
  5. The last step is a write PEF file.
Basic version of dacopan-analyzer supports the following protocols:
  • Arp level - ARP;
  • Network level - IPv4;
  • Transport level - TCP, UDP;
  • Application level - HTTP, DNS.
The protocols for application level defines using port numbers. For each known application protocol dacopan-analyzer has one predefined port number. The events for other protocols includes as "UNKNOWN". User can manually adds other protocols to the produced PEF file.

Options

-i, --ip-address=IP1[,IP2]
Specify IP addresses corresponding to packet trace files. This option requires the argument --- a list of two comma separated IP addresses in standard numbers-and-dots notation. There should be no white spaces inside the list. Alternatively, the option could be specified twice with single IP address as an argument.
-l, --var-log=FILE
Read variables from FILE, containing some host-specific variables, which can not be determined from packet trace logs (not supported).
-o, --output=FILE
Place the output into FILE. This option requires the argument --- the name of the output file. The default output file name is used if the option is not specified.
-t, --time-align=VAL1[,VAL2]
Set time alignments (time difference) between the hosts.
--http=PORT1[,...]
Specify list of HTTP ports
--dns=PORT1[,...]
Specify list of DNS ports
-h, --help
Show brief documentation and exit
-v, --version
Show version information and exit

Protocol events file

The Protocol Events File (PEF) is the interface between Analyzer and Animator modules. It is the output of the Analyzer, it is read by the Animator, and it contains the necessary packet interchange data. Some of this information may as well have been added manually to the PEF. The use of XML has been preferred in an attempt to make the PEF extensible, human-readable and editable.
The DTD (Document Type Definition) to which any PEF must conform follows. It contains information about:
host
Hosts include an id for internal use, its IP address, and maybe a hostname.
flow
Flows include an id, 2 host ids, and their 2 ports.
link
Links include an id and 2 host ids.
layer
Layers include an id and name; inside each layer definition, the protocols particular to that layer can be found.
protocol
Protocol definition includes an id and a name.
variable
Variables contain constant and dynamic variable definitions.
constant
Constants include a name, and maybe a host id, a link id and/or a protocol id. The value of the constant variable is specified after the definition.
variable
Variables (those variables that change from unit to unit, for instance) include name, protocol id and scope (flow/unit/unit-field). Their values are specified later inside the units.
event
Events different types of units compose the actual packet data.
unit_sent
Unit sents include id, source id, destination id, protocol id and may include flow id, time and children id list. Values of dynamic variables are specified inside them.
unit_received
Unit receiveds include an id corresponding to a unit sent id, and the time when the unit was received in destination.
unit_dropped
Unit droppeds have an id and the time when the unit is dropped.
For more detailed information see the "events.dtd" file.

Examples

Analyzer usage

There are some examples of dacopan-analyzer usage:

tcpdump log files and PEF file

The two tcpdump log files contains information about connection using UDP protocol. The textual presentation of these files is following.
dump1
16:37:33.673745 10.0.0.1 > 10.0.0.2: (frag 40657:532@976) (ttl 64, len 552)
16:37:33.874760 10.0.0.1.36568 > 10.0.0.2.36264: [bad udp cksum 2f1!] udp 1500 (frag 40657:976@0+) (ttl 64, len 996)
16:37:35.676990 10.0.0.1 > 10.0.0.2: (frag 40658:556@1952) (ttl 64, len 576)
16:37:35.878496 10.0.0.1 > 10.0.0.2: (frag 40658:976@976+) (ttl 64, len 996)
16:37:35.879481 10.0.0.1.36569 > 10.0.0.2.36265: [bad udp cksum 404a!] udp 2500 (frag 40658:976@0+) (ttl 64, len 996)
dump2
16:37:33.567000 10.0.0.1 > 10.0.0.2: (frag 40657:532@976) (ttl 64, len 552)
16:37:33.567006 10.0.0.1.36568 > 10.0.0.2.36264: [bad udp cksum 2f1!] udp 1500 (frag 40657:976@0+) (ttl 64, len 996)
16:37:35.569742 10.0.0.1 > 10.0.0.2: (frag 40658:556@1952) (ttl 64, len 576)
16:37:35.569748 10.0.0.1 > 10.0.0.2: (frag 40658:976@976+) (ttl 64, len 996)
16:37:35.569892 10.0.0.1.36569 > 10.0.0.2.36265: [bad udp cksum 404a!] udp 2500 (frag 40658:976@0+) (ttl 64, len 996)
Using dacopan-analyzer we produce the following PEF file.
PEF file
<?xml version="1.0"?>
<!DOCTYPE protocol_events SYSTEM "http://www.cs.helsinki.fi/group/dacopan/events.dtd">

<!--
    Created by: dacopan-analyzer version 1.0rc1.
    Tue May 25 18:33:03 2004
-->

<protocol_events>

    <hosts>
        <host id="H1" ip="10.0.0.2"/>
        <host id="H2" ip="10.0.0.1"/>
    </hosts>

    <flows>
        <flow id="F1" host1="H1" port1="36568" host2="H2" port2="36264"/>
        <flow id="F2" host1="H1" port1="36569" host2="H2" port2="36265"/>
    </flows>

    <links>
        <link id="K1" host1="H1" host2="H2"/>
    </links>

    <layers>
        <layer id="L1" name="network">
            <protocol id="P2" name="net_unknown"/>
            <protocol id="P0" name="ipv4"/>
        </layer>
        <layer id="L2" name="transport">
            <protocol id="P5" name="trans_unknown"/>
            <protocol id="P3" name="tcp"/>
            <protocol id="P4" name="udp"/>
        </layer>
        <layer id="L3" name="application">
            <protocol id="P8" name="application_unknown"/>
            <protocol id="P7" name="http"/>
            <protocol id="P6" name="dns"/>
        </layer>
    </layers>

    <variables>
        <variable name="tos" protocol="P0" scope="unit-field"/>
        <variable name="tot_len" protocol="P0" scope="unit-field"/>
        <variable name="id" protocol="P0" scope="unit-field"/>
        <variable name="flag_rf" protocol="P0" scope="unit-field"/>
        <variable name="flag_df" protocol="P0" scope="unit-field"/>
        <variable name="flag_mf" protocol="P0" scope="unit-field"/>
        <variable name="frag_off" protocol="P0" scope="unit-field"/>
        <variable name="ttl" protocol="P0" scope="unit-field"/>
        <variable name="protocol" protocol="P0" scope="unit-field"/>
        <variable name="source_addr" protocol="P0" scope="unit-field"/>
        <variable name="dest_addr" protocol="P0" scope="unit-field"/>
        <variable name="source_port" protocol="P3" scope="unit-field"/>
        <variable name="dest_port" protocol="P3" scope="unit-field"/>
        <variable name="seq" protocol="P3" scope="unit-field"/>
        <variable name="ack_seq" protocol="P3" scope="unit-field"/>
        <variable name="window" protocol="P3" scope="unit-field"/>
        <variable name="urg_pointer" protocol="P3" scope="unit-field"/>
        <variable name="flag_fin" protocol="P3" scope="unit-field"/>
        <variable name="flag_syn" protocol="P3" scope="unit-field"/>
        <variable name="flag_rst" protocol="P3" scope="unit-field"/>
        <variable name="flag_psh" protocol="P3" scope="unit-field"/>
        <variable name="flag_ack" protocol="P3" scope="unit-field"/>
        <variable name="flag_urg" protocol="P3" scope="unit-field"/>
        <variable name="data_offset" protocol="P3" scope="unit-field"/>
        <variable name="source_port" protocol="P4" scope="unit-field"/>
        <variable name="dest_port" protocol="P4" scope="unit-field"/>
        <variable name="len" protocol="P4" scope="unit-field"/>
        <variable name="method" protocol="P7" scope="unit-field"/>
        <variable name="url" protocol="P7" scope="unit-field"/>
        <variable name="version" protocol="P7" scope="unit-field"/>
        <variable name="status_code" protocol="P7" scope="unit-field"/>
        <variable name="phrase" protocol="P7" scope="unit-field"/>
        <variable name="connection" protocol="P7" scope="unit-field"/>
        <variable name="content_length" protocol="P7" scope="unit-field"/>
        <variable name="content_type" protocol="P7" scope="unit-field"/>
        <variable name="cookie" protocol="P7" scope="unit-field"/>
        <variable name="date" protocol="P7" scope="unit-field"/>
        <variable name="host" protocol="P7" scope="unit-field"/>
        <variable name="user_agent" protocol="P7" scope="unit-field"/>
        <variable name="trans_time" protocol="P2 P0 P5 P3 P4 P8 P7" scope="unit"/>
        <variable name="sent_time" protocol="P2 P0 P5 P3 P4 P8 P7" scope="unit"/>
        <variable name="data" protocol="P8 P7" scope="unit"/>
    </variables>

    <events>
        <unit_sent id="U1" source="H2" destination="H1" protocol="P8" time="0.000000" children="U2" flow="F1">
            <value name="sent_time">0.000000</value>
            <value name="trans_time">0.307760</value>
            <value name="data"><![CDATA[\0x00\0x00\0x00\0x00@<\0x97\0x0d\0x00\0x08\0xa6\0xc9DDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD]]></value>
        </unit_sent>
        <unit_sent id="U2" source="H2" destination="H1" protocol="P4" time="0.000000" children="U3 U4" flow="F1">
            <value name="sent_time">0.000000</value>
            <value name="trans_time">0.307760</value>
            <value name="source_port">36568</value>
            <value name="dest_port">36264</value>
            <value name="len">1508</value>
        </unit_sent>
        <unit_sent id="U4" source="H2" destination="H1" protocol="P0" time="0.000000">
            <value name="sent_time">0.000000</value>
            <value name="trans_time">0.106745</value>
            <value name="tos">0</value>
            <value name="tot_len">552</value>
            <value name="id">40657</value>
            <value name="flag_rf">0</value>
            <value name="flag_df">1</value>
            <value name="flag_mf">0</value>
            <value name="frag_off">976</value>
            <value name="ttl">64</value>
            <value name="protocol">17</value>
            <value name="check">34167</value>
            <value name="source_addr">10.0.0.1</value>
            <value name="dest_addr">10.0.0.2</value>
        </unit_sent>
        <unit_sent id="U3" source="H2" destination="H1" protocol="P0" time="0.000006">
            <value name="sent_time">0.000006</value>
            <value name="trans_time">0.307754</value>
            <value name="tos">0</value>
            <value name="tot_len">996</value>
            <value name="id">40657</value>
            <value name="flag_rf">0</value>
            <value name="flag_df">1</value>
            <value name="flag_mf">1</value>
            <value name="frag_off">0</value>
            <value name="ttl">64</value>
            <value name="protocol">17</value>
            <value name="check">25653</value>
            <value name="source_addr">10.0.0.1</value>
            <value name="dest_addr">10.0.0.2</value>
        </unit_sent>
        <unit_received id="U4" time="0.106745"/>
        <unit_received id="U3" time="0.307760"/>
        <unit_received id="U2" time="0.307760"/>
        <unit_received id="U1" time="0.307760"/>
        <unit_sent id="U5" source="H2" destination="H1" protocol="P8" time="2.002742" children="U6" flow="F2">
            <value name="sent_time">2.002742</value>
            <value name="trans_time">0.309739</value>
            <value name="data"><![CDATA[\0x00\0x00\0x00\0x00@<\0x97\0x0f\0x00\0x08\0xb1\0x83DDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD]]></value>
        </unit_sent>
        <unit_sent id="U6" source="H2" destination="H1" protocol="P4" time="2.002742" children="U7 U8 U9" flow="F2">
            <value name="sent_time">2.002742</value>
            <value name="trans_time">0.309739</value>
            <value name="source_port">36569</value>
            <value name="dest_port">36265</value>
            <value name="len">2508</value>
        </unit_sent>
        <unit_sent id="U9" source="H2" destination="H1" protocol="P0" time="2.002742">
            <value name="sent_time">2.002742</value>
            <value name="trans_time">0.107248</value>
            <value name="tos">0</value>
            <value name="tot_len">576</value>
            <value name="id">40658</value>
            <value name="flag_rf">0</value>
            <value name="flag_df">1</value>
            <value name="flag_mf">0</value>
            <value name="frag_off">1952</value>
            <value name="ttl">64</value>
            <value name="protocol">17</value>
            <value name="check">34020</value>
            <value name="source_addr">10.0.0.1</value>
            <value name="dest_addr">10.0.0.2</value>
        </unit_sent>
        <unit_sent id="U8" source="H2" destination="H1" protocol="P0" time="2.002748">
            <value name="sent_time">2.002748</value>
            <value name="trans_time">0.308748</value>
            <value name="tos">0</value>
            <value name="tot_len">996</value>
            <value name="id">40658</value>
            <value name="flag_rf">0</value>
            <value name="flag_df">1</value>
            <value name="flag_mf">1</value>
            <value name="frag_off">976</value>
            <value name="ttl">64</value>
            <value name="protocol">17</value>
            <value name="check">25530</value>
            <value name="source_addr">10.0.0.1</value>
            <value name="dest_addr">10.0.0.2</value>
        </unit_sent>
        <unit_sent id="U7" source="H2" destination="H1" protocol="P0" time="2.002892">
            <value name="sent_time">2.002892</value>
            <value name="trans_time">0.309589</value>
            <value name="tos">0</value>
            <value name="tot_len">996</value>
            <value name="id">40658</value>
            <value name="flag_rf">0</value>
            <value name="flag_df">1</value>
            <value name="flag_mf">1</value>
            <value name="frag_off">0</value>
            <value name="ttl">64</value>
            <value name="protocol">17</value>
            <value name="check">25652</value>
            <value name="source_addr">10.0.0.1</value>
            <value name="dest_addr">10.0.0.2</value>
        </unit_sent>
        <unit_received id="U9" time="2.109990"/>
        <unit_received id="U8" time="2.311496"/>
        <unit_received id="U7" time="2.312481"/>
        <unit_received id="U6" time="2.312481"/>
        <unit_received id="U5" time="2.312481"/>
    </events>

</protocol_events>

Frequently Asked Questions

How can I produce PEF file?
Why produced PEF files does not have events?
The hosts has a different time. How I can correct it?

How can I produce PEF file?

You need two hosts and tcpdump tool in each host. You can use the following sequence:
  1. first start tcpdump in each host with necessary options (for example filters unwanted data)
  2. use the network between hosts (We belive that you know how)
  3. stop tcpdump tools
  4. using analyzer produce PEF file.

Why produced PEF files does not have events?

It seems that you use empty tcpdump log files or wrong IP addresses. Try to use tcpdump tool and you can see what packets are includes in this log files and what IP addresses are used.

The hosts has a different time. How I can correct it?

You can use option -t to increase or decrease time value for each host. Also if analyzer finds packet which was received before sent then it prints message with necessary time addition. But sometimes time grows irregularly and if tcpdump logs are large then is possible that analyzer can not links this logs. You can divide this logs between small parts and makes several short PEF files.

DaCoPAn Animator


Installation

System requirements

Installing Java

If you don't have Java installed, you need to install it before installing the DaCoPAn animator. Follow instructions presented at http://java.sun.com/downloads/.

Downloading DaCoPAn animator

The DaCoPAn products (both analyzer and animator) can be downloaded from the distribution site at http://www.cs.helsinki.fi/group/dacopan/. On that site, select the animator distribution package designed for your system (Linux, Windows, or generic) and download it to your computer. You can also download the full sources from the download site.

Installing DaCoPAn animator

Once you have downloaded the animator distribution package, you can install it simply by unpacking it to a directory of your choise. If you are using the Windows installer, just run it and follow its instructions.

Running DaCoPAn animator

The animator can be run in some alternate ways. You can either run it from command line by typing

java -jar animator.jar

or by clicking on a shortcut (animator.sh in Linux and animator.bat in Windows). When using the Windows installer, shortcuts are also created in the start menu.

To be able to use the animator for anything productive, you also need to have some scenario or protocol event files. To get them, you can either use the DaCoPAn analyzer to create such files or go to the DaCoPAn distribution site and download predefined scenario files. Some example files are also delivered in the animator distribution package.


Screen parts

In this section the different sections of the DaCoPAn animator are briefly explained.

Screen parts

As you can see in the above image, the screen is divided in three main parts: the main animation area, the note area and the UFO panel. In the main animation area there can be two kinds of animation panels: MSC and ENC panels. In addition to these, there also is a tool bar and a status bar. In Scenario mode you can also see a small window for editing and controlling the scenario. That dialog is explained in the scenarios section.

Tool bar

The menu bar

The tool bar provides a fast way to access the most important actions available trough the menu. Those are the basic file operations, animation control, settings and changing layer:

In addition to these, in the menu there are the following commands

Main animation area

The main animation area can be used by either MSC or ENC panel. When the animator is started, a welcome screen is shown in that space.

MSC panel

MSC panel

Message Sequence Chart (MSC) animation is the main animation type in the DaCoPAn animator. It shows the units being transfered between two hosts mapped along a time axis increasing from up to down. The panel is divided in a drawing area that shows the packets moving as lines and a host area that holds information about host variables at specific times in animation. The current time in the animation is shown as a horizontal blue line ("now line").

ENC panel

ENC panel

The ENC panel shows the encapsulation of a selected transfer unit. The selected unit is marked with a red border. To get out of the ENC view, there is a button: "Quit encapsulation".

Ufo panel

ENC panel

The UFO panel visualizes the units moving in the MSC panel in a more visual way as boxes. It is always used together with the MSC animation panel and when the main animation area is used by the ENC panel, the UFO stays empty.

Notes panel

ENC panel

The note panel displays notes that can be attached to either time and layer (MSC panel) or a specific encapsulation view (ENC). In MSC mode the note panel always shows the last note. The note panel can also be used for adding, deleting and editing notes.

Status bar

ENC panel

The status bar contains two important sections: On its left side, there is a display showing which animator mode (scenario or explore mode) is currently active. The active one is highlighted and the other one grayed. On the right corner there is a panel displaying current time in the actual network communication animated.

When the animator is in scenario mode, the scenario playlist window can be minimized to the status bar. Then it appears on the right side of the animator mode display and by clicking the title, the window appears again.


Files

File types

The Animator works with two different types of files:

PEF files contain protocol data (packet data and information on other essential entities, such as hosts, protocols and network layers) produced by the Analyzer out of protocol logs created with tcpdump. These files can be opened and viewed in the Animator. However, as the contents of PEF files vary significantly from one file to the other, the settings of the Animator often require tweaking before the data in the file can be visualized in a meaningful way.

For example, some PEF files may contain protocol units that are sent and received within a couple of milliseconds (as is the case in a local area network) and in other files it might take the units several hundred milliseconds to arrive (modem connection to the internet, for example). Thus it's often necessary to adjust the visual scale -setting of the Animator to make the information on the units readable.

Any changes made to Animator settings can't be saved in the PEF file itself. However, there is another file type, Scenario File, that's designed to contain the protocol events data along with settings set by the user. A scenario file can also contain a sequence of animations recorded by the user as well as any notes attached to the animations.

Loading files

Both PEF and scenario files can be loaded using the same procedure. To bring up the dialog for choosing which file to load, you should either


Image 1: Accessing the file selection dialog

After the file selection dialog has opened, you can set the file filter either to show PEF files, scenario files or all files.


Image 2: Selecting a file

To load a file, double-click on it, or select it using a single mouse click and then press the Open button. When the file is being loaded, a progress dialog is shown (see Image 3).


Image 3: Progress dialog

If no errors are reported, the file was valid and the Animator is ready to run!

Saving files

When any changes are made to a file (either a PEF or a scenario file) loaded into the Animator, the name of the file shown in the titlebar of the application is suffixed with an asterisk, i.e. the character '*' (see Image 4).


Image 4: The asterisk indicates a file with unsaved changes

As explained in the previous chapter, the Animator only saves scenario files. If any changes are made to a PEF file, they need to be saved in a new scenario file. To save a PEF file to a scenario file, you can either

This will bring up a file selection dialog similar to the one used when loading files. Use the dialog to type in the name of the scenario file you'd like to create (or select an existing file to overwrite it). See Image 5 for an example.


Image 5: Typing in the name of a new scenario file

If a scenario file is already loaded into the Animator, accessing the Save... menu item or activating the Ctrl+S hotkey automatically saves the latest changes to the existing scenario file. It is naturally also possible to save the scenario to a new file. To do this, you must select the Save as... menu item from the File menu.


Settings

The DaCoPAn animator can be tuned to adapt it to the different user purposes. The setting panels are the interface for the user to set the animator parameters.

Accessing the setting panels

There are two ways to access to the setting panels:

From the main toolbar clicking on the icon for the settings
The settings icon

From the menu: File->Settings
Accessing to the settings through the menu

Types of settings

There are some different types of settings depending on their functionality. They have been divided into three basic categories

Scale Settings

Setting up the animation display size and the speed of it are the most basic features of the animator and the user will need to tune them often to get the visualization. The scale settings panel contain some elements that will made easier to adjust these values.

Scale settings Panel
Scale settings

Elements to display in a layer

The MSC animation lets the user to show some information about the network units while the animation is running. There are two types of data that can be shown in the screen: variables (host-dependent values that are changed during the network transactions) and protocol header fields (value extracted from the header of a message exchanged in the network).

Protocol header fields and variables are values specific to a layer, so the animator creates a panel per layer to select the fields and variables to display. These selection are made through two separeted lists that contain the different variables and fields for the different protocols in that layer.

These selections are made by single-clicking on the different items in the list. No group selections are allowed. To deselect an item just single-click it again. Due to screen space issues when drawing the animation the number of variables and header fields that can be swown has been limited. The actual limits for them are 3 variables and 5 protocol header fields. If this limits are reached a message is displayed, as you can see in the figure.


Layer settings panel

The variables and protocol header fields are displayed in different places in the MSC animation. The variables are shown in the columns every time that a message unit is sent or received (message unit event). The protocol header fields are displayed over the lines that represent the message unit.


Variables and protocol header fields represented in the MSC animation

Performance settings

These settings let the user select the load of the animator over the system in wich is running.

Performance settings panel
Performance settings

Settings and working modes

The panels displayed to change the settings are different depending on the working mode of the DaCoPAn animator, due to the different purposes of the two modes.

Explore mode

In the explore mode the complete set of settings can be configured, these are settings are:

Scenario mode

A smaller number of settings can be configured here. Due to the purpose of creating a item for the scenario playlist, only the settings needed for one of those items is displayed:


The autoplay checkbox in the layer settings panel

Another place where the setting panels can be invoked is from the recording mode of the scenario playlist. In the scenario playlists the MSC elements settings can be edited by pressing the edit button. The panels open to edit the element settings are the same as the ones for the scenario mode but the values changed are the ones that the MSC element contain.


Editing and msc item in the scenario playlist


Controlling the animation

The animation is controlled either through the tool bar or commands in the menu. The basics of animation controlling are presented in this section.

Play ⁄ Pause

When an animation is loaded in the animator, it is in paused mode. In this mode you can scroll the MSC area and step to specific places in time by clicking on the MSC panel. When you want to watch the animation as a continuos stream of events, you can just click on the play button.

When the animator is playing the animation, other buttons than pause become grayed, and if you want to do something else than just watch the animation, you must first press pause.

Stepping

When the animation is paused, you can use the stepping buttons to step in the animation. The stepping moves the now line to the next or previous event depending on the direction in which you are stepping. Different events in the animation are sending a unit, receiving a unit or a unit being dropped.

Rewinding

Rewind and fast forward buttons can be used to move to the beginning or to the end of the animation.

Display ENC panel

The encapsulation (ENC) panel for a specific unit can be displayed by highlighting the unit in the UFO panel. In upcoming versions of the animator it will be possible to select the unit by clicking on it, but at the moment you need to use the stepping functionality to find the unit you want to highlight (the newest unit is always highlighted).

In the above picture you can see that the gray unit is highlighted and it's data is shown on the left data area. On the second channel (orange) moving from right to left, the last one is highlighted: it has a thicker border and it's data is shown on the right data area.

When you have selected the unit whose encapsulation you want to see, you can show it by clicking on the "show encapsulation" button under the data area for that unit.


Working with scenarios

Explore mode and Scenario mode

A scenario is a 'play list' of different items. You may get a scenario as a ready-made scenario file (extension .sce) or you can create your own scenarios.

To work with scenarios you need to be in 'scenario mode'. The program is always either in 'explore mode' or in 'scenario mode'. You can switch between the modes at any time, regardless of what kind of file you have loaded. You switch the mode in the Animation menu, see picture below.

You can always see the mode you are in by looking at the bottom left corner of the DaCoPAn animator window. When you are working with the animator, either the EXPLORE or the SCENARIO text is always highlighted with blue color. That tells you which mode you are in.

The only difference between the modes is that in scenario mode you have the 'Scenario play list' dialog where you can select scenario items for viewing. Aside from this dialog, in both of the modes ALL other controls available to the user work in EXACTLY the same way.

Scenario play list dialog

The Scenario play list dialog shows the scenario play list and provides ways for showing and editing the list. When the application is in Scenario mode, the Scenario play list dialog is always either visible on screen or appears as minimized in the status bar (see the picture above in previous section). So, in Scenario mode, the dialog is NEVER completely hidden from view. If the dialog is minimized in the status bar, you can always make it visible by simply clicking on the blue rectangle with the text "Scenario play list".

Viewing scenarios

If you just want to view scenarios, make sure you are NOT in recording mode. In the image below you see two versions of the dialog. The version on the left has recording mode OFF and the one on right has recording mode ON.

You can always (when not in recording mode) select an item from the list for viewing. The list is intended to be presented from beginning to the end, so unless you want especially to inspect some item on the list, it's most logical to start from the beginning (top). You can always advance to the next item by clicking on the Next item button. When one item is presented, the program will automatically move to the next item on the list. Depending on what kind of items there are on the list, and some settings for those items, the list may play all the way from beginning to end without user input, or the scenario may require that the user presses the Play button (in the toolbar) or the Next item button (in the Scenario play list dialog) for some of the item. For more details, read about the different scenario items in the next section.

Different scenario items

See the image below for another example of a play list.

MSC item

An MSC item means a presentation of the protocol data on the Message Sequence Chart. An MSC item is presented in the play list in this fashion:

MSC 0.3137->2.0061 [Transport] {1/10} AutoPlay

An MSC scenario item contains information about the following:

Start time - A point in time where the presentation of this item starts. In the above example the start time is 0.3137. When the item is selected from the list, the animation time is set to match this time.

End time - A point in time after the start time. In the above example the end time is 2.0061. When the animation is played to (or past) this time, the scenario will automatically advance to the next scenario item. Note that when the item is being recorded, it will exist in such a state that it has a start time but no end time. To mark this the end time is shown just as * (an asterisk).

Layer - Always just one layer where to present the data. In the above example the layer is Transport.

Settings - All the settings that you can access in scenario mode by the Change settings button (in toolbar) or the Edit item button (in Scenario dialog, only in recording mode) will be saved for the item. The settings are saved independently for each list item, so changing settings for one item doesn't affect the settings for any other item. The settings include the scale settings, the visualization settings for the particular layer, and also the 'AutoPlay' setting that is relevant (and available) only in the scenario mode. As an indication about these settings, the above example line has the part "{1/10}". That tells the magnitude of the scale, and corresponds to the radio button selected in the scale settings.

Meaning of the AutoPlay settings: (notice the text "AutoPlay" in the above example line) When AutoPlay is selected, the item is automatically put to Play mode when selected. (Selecting can happen either when the user clicks the item with mouse, or the scenario advances to that item from the previous item.) Notice that the AutoPlay does NOT have effect when the scenario dialog is in recording mode. This is to make it easier to edit the play list.

ENC item

An ENC item corresponds to an encapsulation of a selected unit. As a scenario item the ENC item is very simple. When the item is selected, the animator will present the encapsulation for the selected unit, and wait for the user to select the Quit encapsulation button. When that is done, the scenario will move to the next scenario item. Or alternatively the user can select the Next item button from the scenario dialog, or just select another item from the play list. The are no editable settings associated with an ENC item.

Pause item

A pause item is a 'non-showable' item in the sense that selecting it doesn't cause any change in the visualization mode of the animator. So when a pause item is selected from the play list, what you will see corresponds always to the PREVIOUS 'showable' item that was selected. (Be aware that if you have selected the Pause item by clicking it on the list, the 'previous' item is not necessarily the one directly above the pause on the list, it is the item that was selected before you clicked the Pause item, whatever the previous item was.)

The only functionality of the pause item is that when the pause item is selected, it pauses the currently playing animation and moves it to the end time of the previous scenario item. (See note above for what exactly is the 'previous' item.)

You may want to use a pause item in the list after an MSC item if you wish the presentation to pause before e.g. changing layer or going into encapsulation. By using the pause item you can have the program pause so that the end of the previous MSC item is still visible.

End marker item - "(end)"

This item behaves in much the same way as the pause item. There is always exactly one end marker in the play list - at the end. What is it for? Always, when you add a new item to the play list, it is added BEFORE the item that is currently selected. So, if you want to add something as the last (real) item in the list, you need to select the end marker and then add your item.

Recording your own scenarios

Most of what you need for recording your own scenarios has already been told previously on this section. This chapter will concentrate of some this-far-unexplained features of the recording mode.

When you are in recording mode, your scenario dialog will look like the dialog on the right below:

The buttons have the following meanings:

Recording mode - toggles the recording mode on and off.

Next item - advances to the next item on the list.

Insert encapsulation - Inserts the currently visible encapsulation (only available when one is visible) to the current position in the play list. (Also see the 'Automated recording actions' section below for another way of recording ENC items.)

Edit item - Shows the settings dialog for the current MSC item. Only available when an MSC item is selected.

Record start - Inserts a new MSC item, with the current time as the start time of the item. Only available in MSC mode and only when there are no unfinished MSC items on the list.

Record end - Sets the current end time as the end time for the currently unfinished MSC item. Only available in MSC mode and when there is an unfinished item. If the current time is before the start time of the unfinished item (end time cannot be before start time!), an error message is shown.

Delete item - Deletes the currently selected item.

Insert pause - Inserts a pause in the current position in the list.

Automated recording actions

Always when you are in recording mode, the following recording actions are carried out automatically:

New MSC item is recorded when you press Play - Whenever you press the Play button, a new MSC item is added to the current position in the list. The functionality is as if the Record start button had been pressed simultaneously.

Encapsulation will be inserted when you press Encapsulation - Whenever you press one of the Encapsulation buttons inside the Unit Flow panel, the encapsulation is inserted in the play list as if Insert encapsulation had been pressed.

Finishing unfinished items - Whenever you have an unfinished MSC item on the list (MSC item without an end time) and you try to insert a new item in the list (either explicitly or implicitly) OR change the layer, the program will try to record the current time as the end time for the unfinished item. If this is not possible, an error message is shown and the action you tried to do is cancelled.

These automated actions aim at making the recording of scenarios more intuitive and effortless.

Notes on recording scenarios

By using the Pause items and the AutoPlay settings it is possible to flexibly create scenarios with quite different paces. Using plenty of the AutoPlay you can make scenarios that play from beginning to end with the only necessary user interaction being pressing the 'Quit encapsulation' button to get out of encapsulation mode. Using plenty of the Pause item and not using the AutoPlay feature it's possible to create scenarios that wait for user actions (either the Next item button or the Play button, depending on situation) before any changes in the mode happen.


Frequently Asked Questions (FAQ)

How do I see something on the screen?
How do I load files?
Why are some of the controls grey and not available?
How can I see all of the variables for a unit in the Unit Flow window?
How can I see all of the variables / fields in a unit when I'm viewing the encapsulation?
Why does the note panel take up so much space?
There are too many packets on top of eachother, is there anything I can do about it?
Why are the units just horizontal lines on the screen?
What if I want to create my own PEFs?
What does it mean that one of the units has a red border in the encapsulation?
How can show the encapsulation of a particular unit?
Where is the language selection menu?
How does the settings dialog work?

How do I see something on the screen?

You need to load something first. A good choice is loading a pre-designed scenario file (xxx.sce). If none are available, you can also load a protocol events file (yyy.pef), which contains raw protocol data from a recorded protocol exchange. After you have loaded the file, you can press play to see something. You will be looking at the lowest layer of the exchange, and the now-line will begin to move downward and show lines in the message sequence chart as the protocol events occur. Be sure to note that you may well need to make some settings changes if you are looking at a PEF file, because many pef files contain protocol envents that happen very rapidly, and will overlap with the default settings. See other sections in this manual for tips on how to proceed from here.

How do I load files?

Press the load button in the upper left corner of the window, marked with an icon of a folder. After this you need to select wether you want to load a scenario file or a PEF file. The default is scenario file. In some cases there might not be any scenario files available, in this case you will not see anything in the file dialog by default.

Also see the manual section on loading and saving files.

Why are some of the controls grey and not available?

Because they are not relevant or possible actions in the situation you are currently in. Examples of this would be that "play" is not a relevant action if there is no file loaded. Another example would be that it's not possible to press play if you are already playing.

How can I see all of the variables for a unit in the Unit Flow window?

By dragging the note panel divider bar downwards until the variable area is tall enough to show all the variables you need to see.

How can I see all of the variables / fields in a unit when I'm viewing the encapsulation?

Unfortunately it's not possible at this time. The vertical space availble it divided evenly among the relevant layers, and it's not possible to resize the layers. A good option is to view the unit that you want to see in the Unit Flow animation, and see all the variables there.

Why does the note panel take up so much space?

In some cases the note panel will take up the whole vertical space on the right side of the screen by default. You can freely resize the note panel by dragging the divider.

There are too many packets on top of eachother, is there anything I can do about it?

No. However, you can try to alleviate this problem by zooming in until the units are not quite so simultaneous. This zooming is best done by selecting a larger network-to-animation ratio, like the 0.01s -> 1s option for instance. Setting the visual scale is also important in this case. Remember that zooming in to the maximum will cause the rest of the animation to be very tedious to watch. As an example, a millisecond of network time, when viewed up close, will cause 10 seconds of inactivity in the network to seem like a lifetime. Your best option is to take a very small clip of interesting network activity, and record a scenario where this clip is zoomed in, but the rest of the animation is "normal".

Why are the units just horizontal lines on the screen?

Due to the fact that the events happen very quickly in the network, and you are viewing the animation with a very coarse scale. You need to change the scale settings so that these "fast" units are shown with more vertical scale. Once again, remember that the rest of the animation might become a mile long if you set the pixel height to be enormous. See the question about packets on top of eachother for another explanation of this same phenomenon.

What if I want to create my own PEFs?

It's not too difficult, but takes a bit of effort. For this you will need 3 things: a) a network with at least 2 machines (a real network works as well as a simulated, if you know how to simulate a network properly) b) the ability to run tcpdump on these 2 machines simultaneaously. c) the DaCoPAn analyzer program running on a Linux machine to analyze the dumps into a pef file. There is more on this in the specific help of the analyzer. There you can read about the particular tips and tricks you might need to get what you want into the pef.

What does it mean that one of the units has a red border in the encapsulation?

This simply means that it is the unit which you had selected when you pressed the button to show the encapsulation diagram. It is the unit who's encapsulation you are viewing. In practise this means that the unit with the border was the last/newest unit sent from the host at the time of the nowline. For a very technical explanation of exactly how the diagram is generated/selected, see the source code comments of fi.helsinki.dacopan.model.ENCTreeModel.java

How can show the encapsulation of a particular unit?

Two good ways to select which unit to view are

a) when the MSC animation is in pause mode (for instance rewound to the end) you can move the now-line by dragging it with the mouse. This will let you move to the unit who's encapsulation you wish to see.

b) pressing the step buttons can also let you choose which unit is "selected", you can see which unit is selected by looking at the Unit Flow diagram's variable boxes. Remember that the stepping moves through events, not units. So 2 consecutive events might be the sending and then the receiving of the same unit, in both cases that unit will be "selected".

Where is the language selection menu?

The language selection menu has also been translated, so if it is localized into a language that you don't know, you can find it by selecting the fourth menu item from the left. (It might also prove interesting to take a moment or two to learn what the word "language" is in all the localized languages!)

How does the settings dialog work?

It contains one tab for each layer present in the animation, plus one tab for scale setting, and one tab for performance settings.

In the layer sections the idea is to select variables and fields from the 2 listboxes. The left side has the variables which will be represented as columns in the MSC, and the right side has the fields which you can select to be drawn on top of each unit's sequence line in the MSC. Remember that there are limitations to how many of each you can select.

The scale settings are best understood after a small amount of experimentation, because the importance and usefullness of the scale settings depends strongly on the data being viewed. Therefor it is recommended that you play with these settings a little bit in order to best understand their effects.

The performance settings are simply to provide a small amount of configurability in order to help those users who have slightly less processing power to be able to use DaCoPAn efficiently. The animator has been optimized as best as is reasonably possible, but setting the antialiasing can bring further increase in performance if disabled.


Last revision: May 31, 2004