==============================================================================
==============================================================================


       @@@@@@@ @@@@@@@ @@@@@@@ @@@@@@@ @@@@@@@ @@@@@@@ @@@@@@@ @@@@@@@
       @@        @@@     @@@   @@      @@   @@ @@      @@   @@ @@   @@
       @@@@@@    @@@     @@@   @@@@@@  @@@@@@  @@      @@@@@@@ @@@@@@
       @@        @@@     @@@   @@      @@  @@  @@      @@   @@ @@
       @@@@@@@   @@@     @@@   @@@@@@@ @@  @@@ @@@@@@@ @@   @@ @@     NG

                      Copyright 2001-2013 The Ettercap Dev Team

==============================================================================
==============================================================================

"Debugging is twice as hard as writing the code in the first place.
Therefore, if you write the code as cleverly as possible, you are,
by definition, not smart enough to debug it." - Brian W. Kernighan


If you found a new bug please report it to
https://github.com/Ettercap/ettercap/issues or by sending an email to
<ettercap-users@lists.ettercap-project.org>


==============================================================================
                     C O M P I L E  T I M E    B U G S
==============================================================================

If you are not able to compile ettercap on your system, please make a bug
report. In order to help you fix the problem we need the following
information:

1) a description of your operating system (including any patch level)

   # uname -a > os.log

2) the cmake cache file

   # cat CMakeCache.txt

3) the entire output from 'make'

   # make 1> make_output 2> make_error 

4) make a tarball with all the needed infos
   
   # tar pczf compile_error.tar.gz os.log \
                                   CMakeCache.txt \
                                   make_output \
                                   make_error

==============================================================================
                           R U N T I M E    B U G S
==============================================================================


If the bug is critical and results in a segmentation fault follow these steps
to make a detailed bug report in order to help us to find the bug and fix it.

1) recompile the program in debug mode:

  (follow the instructions on README.GIT file in order to pull the repository and build the program in debug mode)


2) force ettercap to not drop privileges to make sure the core is dumped:

   # export EC_UID=0
   # export EC_GID=0


3) override any limit for coredumps:

   # ulimit -c unlimited


4) enable memory checks (if your system supports them), so the program will
   abort if some heap corruption is in place:

   # export MALLOC_CHECK_=2
   

5) dump to a file the traffic that causes the crash (we need it to reproduce
    the situation)

   # ./src/ettercap -w offending_packets.pcap ... --your-options-here ...


6) analyze the core with gdb and send us the backtrace:

   # gdb ettercap core
   
   (gdb) bt
   (gdb) quit

   copy and paste the output of the gdb command 'bt' in a file (backtrace.log)

6a) if you don't get a core (for any reason), you can run ettercap within gdb:

   # gdb ettercap
   
   (gdb) r your_parameters_here

   when it catches the segfault, you can get the backtrace with the 'bt'
   command


7) collect useful information about your network:

   # ifconfig -a > network.txt
   # arp -an >> network.txt
   # netstat -rn >> network.txt
   

8) tar all the information together with the log generated by ettercap:

   # tar zcvf bugreport.tar.gz ettercap-*-debug.log \
                               offending_packets.pcap \
                               network.txt \
                               backtrace.log


9) mail the tarball to us with a brief description of the bug.

=============================================================================

vim:ts=3:expandtab

