doc/bugs

   1 BUGS
   2
   3 0.INTRODUCTION
   4
   5   The FreeRADIUS web site is at <URL: http://www.freeradius.org>, and
   6   most information referenced in this document can be found there.
   7
   8   This is primarily for non-developers of the FreeRADIUS server. If you are
   9   able to patch the code to work correctly, then we invite you to join the
  10   development list to discuss it. If you're the type who know little about
  11   how to code, then this is the place for you!
  12
  13 1.YOU FOUND A BUG
  14
  15   So you think you've found a bug in the FreeRADIUS server?
  16
  17   You should first discuss it on the users list, to see if anyone can
  18   reproduce it. Often there's a simple explanation of why the server
  19   behaves as it does, and it's not necessarily a bug in the code, so
  20   browse the lists' archives of the last two months, and if you don't
  21   see messages about it, ask!
  22
  23   If the behavior is correct but confusing, we think that's a bug too, and
  24   you should file a bug against our documentation.
  25
  26   For more information about the users list, the lists' archives and the
  27   faq, please visit http://www.freeradius.org/list/users.html
  28   Please make sure to READ and RESPECT the house-rules. You will get much
  29   better response and much faster if you do!
  30
  31 2.CORE DUMPS
  32
  33   If the server, or one of the accompyaning programs core dumps, then
  34   you should rebuild the server as follows:
  35
  36   $ ./configure --enable-developer
  37   $ make
  38   $ make install
  39
  40   and then run the program again. You may have to to enable core
  41   dumps, via:
  42
  43   $ ulimit -c unlimited
  44
  45   When it core dumps, do:
  46
  47   $ gdb /path/to/executable /path/to/core/file
  48
  49   Enable logging in gdb via the following commands:
  50
  51   (gdb) set logging file gdb-radiusd.log
  52   (gdb) set logging on
  53
  54   and follow the instructions in section 4, below.
  55
  56 3. DEBUGGING A LIVE SERVER
  57
  58   If you can't get a core dump, or the problem doesn't result in a
  59   core dump, you may have to run the server under gdb.  To do this,
  60   ensure that you have symbols in the binaries (i.e. a non-stripped
  61   binary) by re-building the server as described in the previous
  62   section.  Then, run the server under gdb as follows:
  63
  64   $ gdb radiusd
  65
  66   Enable logging in gdb via the following commands:
  67
  68   (gdb) set logging file gdb-radiusd.log
  69   (gdb) set logging on
  70
  71   Tell gdb to pass any necessary command-line arguments to the
  72   server:
  73
  74   (gdb) set args ...
  75
  76   Where the "..." are the command-line arguments you normally pass to
  77   radiusd.  Fo debugging, you probably want to do:
  78
  79   (gdb) set args -f
  80
  81   Then, do:
  82
  83   (gdb) run
  84
  85   When something interesting happens, you can hit CTRL-C in the
  86   window, and you should be back at the gdb prompt:
  87
  88   (gdb)
  89
  90   And follow the instructions in section 4, below.
  91
  92 4. OBTAINING USEFUL INFORMATION
  93
  94   If the server was built with threads, you can do:
  95
  96   (gdb) info threads
  97
  98   Which will give you information about the threads.  If the server
  99   isn't threaded, that command-line will print a message saying so.
 100
 101   Then, do:
 102
 103   (gdb) thread apply all bt full
 104
 105   If the server isn't threaded, the "thread apply" section isn't necessary
 106
 107   The output should be printed to the screen, and also sent to the
 108   gdb-radiusd.log file.  Copy the log gile and mail it to the list, or
 109   put it on a web page if it's too large.  Include the name of the
 110   operating system.
 111   Without this information, it's impossible for anyone to know why the
 112   program core dumped.
 113
 114   You can also submit the information to the bug database at:
 115
 116     http://bugs.freeradius.org/
 117
 118   Submitting it to the bug database ensures that the bug report won't
 119   get forgotten, and that someone will eventually respond to it.
 120
 121
 122 5. VALGRIND
 123
 124   On Linux systems, "valgrind" is a useful tool that can catch certain
 125   classes of bugs.  To use it, run the server voa:
 126
 127 $ valgrind --tool=memcheck --leak-check=full radiusd -Xm
 128
 129   It will print out certain kinds of errors to the screen.  There may
 130   be a number of errors related to OpenSSL, dlopen(), or libtldl.  We
 131   cannot do anything about those problems.  However, any errors that are
 132   inside of the FreeRADIUS source should be brought to our attention.
 133
 134
 135 6. Running with "screen"
 136
 137   If the bug is a crash of the server, and it takes a long time for the
 138   crash to happen, perform the following steps:
 139
 140  * log in as root
 141  * open a screen session (http://blogamundo.net/code/screen/)
 142    $ screen bash
 143  * make sure FreeRADIUS is not running
 144  * make sure you have all the debug symbols about, or a debugable
 145    version of the server installed
 146  * configure screen to log to a file; 'Ctrl-A H'
 147  * type 'gdb /path/to/radius'  (or /path/to/freeradius on Debian)
 148  * at the (gdb) prompt, type 'run -X'
 149  * detach from screen 'Ctrl-A D'
 150  * when you notice FreeRADIUS has died, reconnect to your screen session
 151    $ screen -D -r
 152  * at the (gdb) prompt type 'where' or for *lots* of info try
 153    'thread apply all bt full'
 154  * tell screen to stop logging, 'Ctrl-A H'
 155  * logout from screen
 156
 157 --
 158
 159 FreeRADIUS Project, copyright 2008
 160 $Id$