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