Providing debug information

Introduction

When you experience a bug in ettercap and raise an issue on Github, it's quite probable that you'll be asked to recompile ettercap from the Github source in debug mode, in order to provide a debug log file.

Since this short sentence may sound quite scary for some people who never got in touch with that, this Wiki page is intended to explain the background and give some guidance through this process.

Background

Ettercap processes network data. Sometimes there are such unthinkable things on the wire, or the environment (computer) is set up quite uncommonly that Ettercap may not be prepared and you face a unwanted behavior or even worse a crash due to a segmentation or memory fault.

When you report such an issue, all these things are not known to the developers and contributors of Ettercap who are willing helping you. Since we can not have access to your computer to troubleshoot the problem directly, we heavily rely on the information that is provided. The more detailed, the more accurate, the better.

In most cases, you're probably using a pre-compiled version of Ettercap coming from your favorite distribution. This is in general good as this way, automatic upgrades are systematically addressed. But the pre-compiled versions of Ettercap do not generate much data which is useful for debugging, as Ettercap is supposed to do something else than collecting debug information.

However in the event to troubleshoot your problem, you need to put some efforts in order to provide this information.

Process

Clean your system from the distribution provided version of Ettercap

First you need to purge Ettercap from your computer.

An example for a Debian based system would look like:

# apt-get purge ettercap

Sometimes the package is called differently so it makes sense to check how it's named and which sub-components also exist (e.g. libettercap).

# apt-get search ettercap

Install dependencies necessary to build Ettercap from source

Ettercap depends on a number of libraries.

# apt-get install debhelper bison check cmake flex ghostscript libbsd-dev \
          libcurl4-openssl-dev libgeoip-dev libltdl-dev libluajit-5.1-dev \
          libncurses5-dev libnet1-dev libpcap-dev libpcre3-dev libssl-dev \
          libgtk-3-dev libgtk2.0-dev 

This example works on Debian, but other distribution may have named the package names slightly different. Use the package manager's search functionality to find the correct name.

To get the source code from Github, it's also recommended to install the git binary package.

# apt-get install git

Now all dependencies should be met to be ready to fetch the source code and compile and install. [Feel free to edit this page and complete the install commands for other distributions / package managers.]

Fetch source code from GitHub

The way working with git described in this section is not optimal if you're planning to hand in a fix on your own. Please read this wiki page which is dedicated to give guidance and tips how to work with git when you plan to work on your own fixes or features. The way how git is used described here just focuses on the ability to provide the debug information to troubleshoot your problem.

First navigate to an appropriate directory. Then issue the following command to clone the Ettercap repository to your local machine and after that change into the cloned source directory.

$ git clone https://github.com/Ettercap/ettercap
$ cd ettercap

Configure and compile and install Ettercap

This is the essential step to tell the build routine to include the debug output calls when building Ettercap. First you need to create a dedicated build directory where the temporary build files are stored. In this directory the configure and make commands need to be issued.

$ mkdir build
$ cd build
$ cmake -DCMAKE_BUILD_TYPE=Debug -DENABLE_IPV6=On ..
$ make
$ sudo make install

The last step installs / copies the built binary and configuration files at their appropriate places. After that Ettercap can be started by just calling ettercap [OPTIONS] on the terminal.

$ sudo ettercap -G

Just as an example.

Reproducing the issue and collecting the debug information

Now redo the steps to reproduce the issue you're facing. Please note, that it may be possible, that you cannot reproduce the issue with an Ettercap version build from the latest source code. This may be because the issue may have already been fixed in source code, but a new version of Ettercap hasn't yet been released or the maintainer of your distribution doesn't have backported the fix into the distribution package.

To provide enough information, a packet capture is always helpful. Call Ettercap with the -w <pcap file> paramter so that all packets Ettercap sees, are stored in this capture file.

$ sudo ettercap -G -w packets.pcap

After you've reproduced the issue, you'll find the debug file in the directory where Ettercap has been executed. It's named following the below naming.

ettercap-<version>_debug.log

The same applies for Ettercap's utils etterfilter and etterlog, but then the prefix is the name of the utility binary.

If your problem produces a segmentation fault, a file named core is being stored in the working directory. This file is also useful as it contains the memory snapshot of Ettercap at the time the segmentation fault occurred.

Now pack the debug logfile(s), the packet capture file and if applicable the core file into a ZIP file and attach it to the issue.

Cleaning up your system

Since you've now installed a version of Ettercap that is outside the upgrade mechanisms of your distribution, you may want to uninstall the Github version of Ettercap. For that go to the build directory created previously and issue the following command.

$ sudo make uninstall

After that you can just delete the ettercap directory where the source code has been cloned to. You can now reinstall the Ettercap package from your distribution.