New build path variable

[freeradius.git] / doc / bugs

diff --git a/doc/bugs b/doc/bugs
index 68d8882..2d6d878 100644 (file)
--- a/doc/bugs
+++ b/doc/bugs
@@ -46,12 +46,67 @@ BUGS
 
   $ gdb /path/to/executable /path/to/core/file
 
-  And then in 'gdb', do:
+  Enable logging in gdb via the following commands:
 
-  $ bt
+  (gdb) set logging file gdb-radiusd.log
+  (gdb) set logging on
 
-  Copy the output, and mail it to the list, along with the name of the
-  program you were running, and the name of the operating system.
+  and follow the instructions in section 4, below.
+
+3. DEBUGGING A LIVE SERVER
+
+  If you can't get a core dump, or the problem doesn't result in a
+  core dump, you may have to run the server under gdb.  To do this,
+  ensure that you have symbols in the binaries (i.e. a non-stripped
+  binary) by re-building the server as described in the previous
+  section.  Then, run the server under gdb as follows:
+
+  $ gdb radiusd
+
+  Enable logging in gdb via the following commands:
+
+  (gdb) set logging file gdb-radiusd.log
+  (gdb) set logging on
+
+  Tell gdb to pass any necessary command-line arguments to the
+  server:
+
+  (gdb) set args ...
+
+  Where the "..." are the command-line arguments you normally pass to
+  radiusd.  If you don't normally pass command-line arguments, this
+  line is not necessary.
+
+  Then, do:
+
+  (gdb) run
+
+  When something interesting happens, you can hit CTRL-C in the
+  window, and you should be back at the gdb prompt:
+
+  (gdb)
+
+  And follow the instructions in section 4, below.
+
+4. OBTAINING USEFUL INFORMATION
+
+  If the server was built with threads, you can do:
+
+  (gdb) info threads
+
+  Which will give you information about the threads.  If the server
+  isn't threaded, that command-line will print a message saying so.
+
+  Then, do:
+
+  (gdb) thread apply all bt full
+
+  If the server isn't threaded, the "thread apply" section isn't necessary
+
+  The output should be printed to the screen, and also sent to the
+  gdb-radiusd.log file.  Copy the log gile and mail it to the list, or
+  put it on a web page if it's too large.  Include the name of the
+  operating system.
   Without this information, it's impossible for anyone to know why the
   program core dumped.
 
@@ -62,7 +117,43 @@ BUGS
   Submitting it to the bug database ensures that the bug report won't
   get forgotten, and that someone will eventually respond to it.
 
+
+5. VALGRIND
+
+  On Linux systems, "valgrind" is a useful tool that can catch certain
+  classes of bugs.  To use it, run the server voa:
+
+$ valgrind --tool=memcheck --leak-check=full radiusd -Xm
+
+  It will print out certain kinds of errors to the screen.  There may
+  be a number of errors related to OpenSSL, dlopen(), or libtldl.  We
+  cannot do anything about those problems.  However, any errors that are
+  inside of the FreeRADIUS source should be brought to our attention.
+
+
+6. Running with "screen"
+
+  If the bug is a crash of the server, and it takes a long time for the
+  crash to happen, perform the following steps:
+
+ * log in as root
+ * open a screen session (http://blogamundo.net/code/screen/)
+   $ screen bash
+ * make sure FreeRADIUS is not running
+ * make sure you have all the debug symbols about, or a debugable 
+   version of the server installed
+ * configure screen to log to a file; 'Ctrl-A H'
+ * type 'gdb /path/to/radius'  (or /path/to/freeradius on Debian)
+ * at the (gdb) prompt, type 'run -X'
+ * detach from screen 'Ctrl-A D'
+ * when you notice FreeRADIUS has died, reconnect to your screen session
+   $ screen -D -r
+ * at the (gdb) prompt type 'where' or for *lots* of info try
+   'thread apply all bt full'
+ * tell screen to stop logging, 'Ctrl-A H'
+ * logout from screen
+
 --
 
-FreeRADIUS Project, copyright 2004
+FreeRADIUS Project, copyright 2008
 $Id$