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