README.BUGS

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


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

                      Copyright 2001-2004 ALoR & NaGA

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

"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 by sending an email to
<alor@users.sf.net> or <naga@antifork.org>, hoping that that part was not 
coded as cleverly as possible... ;)

==============================================================================
                     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
informations:

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

   # uname -a > os.log

2) the log file generated by configure 

   # cat config.log

3) the entire output from 'make'

   # make 1> make_output 2> make_error 

4) make a tarball with all the needed infos
   
   # tar zxvf compile_error.tar.gz os.log \
                                   config.log \
                                   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:

   # ./configure --enable-debug ... --your-options-here ...


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)

   # ./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 informations together with the log generated by ettercap:

   # tar zcvf bugreport.tar.gz ettercapNG-*-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