+BUGS
-( The FreeRADIUS web site is at <URL: http://www.freeradius.org/>, and
-most information referenced in this document can be found there. A web
-interface to the BTS can be found at <URL: http://bugs.freeradius.org/>.)
+0.INTRODUCTION
-This is primarily for non-developers of the FreeRADIUS server. If you are
-able to patch the code to work correctly, then we invite you to join the
-development list to discuss it. If you're the type who know little about
-how to code, then this is the place for you!
+ The FreeRADIUS web site is at <URL: http://www.freeradius.org>, and
+ most information referenced in this document can be found there.
+ This is primarily for non-developers of the FreeRADIUS server. If you are
+ able to patch the code to work correctly, then we invite you to join the
+ development list to discuss it. If you're the type who know little about
+ how to code, then this is the place for you!
-= So you think you've found a bug in the FreeRADIUS server
+1.YOU FOUND A BUG
-You should first discuss it on the users list, to see if anyone can repro-
-duce it. Often there's a simple explanation of why the server behaves as
-it does, and it's not necessarily a bug in the code, so browse the lists'
-archives of the last two months, and if you don't see messages about it,
-ask!
+ So you think you've found a bug in the FreeRADIUS server?
-If the behavior is correct but confusing, we think that's a bug too, and
-you should file a bug against our documentation.
+ You should first discuss it on the users list, to see if anyone can
+ reproduce it. Often there's a simple explanation of why the server
+ behaves as it does, and it's not necessarily a bug in the code, so
+ browse the lists' archives of the last two months, and if you don't
+ see messages about it, ask!
+ If the behavior is correct but confusing, we think that's a bug too, and
+ you should file a bug against our documentation.
-= Looking at core dumps
+ For more information about the users list, the lists' archives and the
+ faq, please visit http://www.freeradius.org/list/users.html
+ Please make sure to READ and RESPECT the house-rules. You will get much
+ better response and much faster if you do!
-If the server, or one of the accompyaning programs core dumps, then
-you should rebuild the server as follows:
+2.CORE DUMPS
-$ ./configure --enable-developer
-$ make
-$ make install
+ If the server, or one of the accompyaning programs core dumps, then
+ you should rebuild the server as follows:
- and then run the program again. When it core dumps, do:
+ $ ./configure --enable-developer
+ $ make
+ $ make install
-$ gdb /path/to/executable /path/to/core/file
+ and then run the program again. You may have to to enable core
+ dumps, via:
- And then in 'gdb', do:
+ $ ulimit -c unlimited
-$ bt
+ When it core dumps, do:
- 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.
-Without this information, it's impossible for anyone to know why the
-program core dumped.
+ $ gdb /path/to/executable /path/to/core/file
+ Enable logging in gdb via the following commands:
-= Filing a bug report
+ (gdb) set logging file gdb-radiusd.log
+ (gdb) set logging on
-If you see something that's obviously a bug, and the developers agree,
-then you should keep 'em from forgetting about it by filing a bug report.
-Using the bug-tracking system (often called 'BTS') is rather easy, once
-one understands how it works.
+ and follow the instructions in section 4, below.
-Since few (if any!) of the developers have ever met each other in real
-life, it's sensible to use the only communication method everyone is
-accustomed to; the BTS uses email messages to do _everything_.
+3. DEBUGGING A LIVE SERVER
-Don't send HTML or any attachments, please. If you don't know what this
-means, and you're using some mailer like Netscape Communicator or
-Microsoft Outlook, please ask someone first. No HTML. No Rich-text. No
-GPG/PGP signed messages. No vcards. ** Plain text only! **
+ 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:
-To submit a bug report, you should mail 'submit@bugs.freeradius.org' with
-a well-defined structure in the body: First a header, then a description.
+ $ gdb radiusd
-The first non-empty line in the body of the message should describe what
-part of the project needs help, using the "Package: " line. What follows
-"Package: " should be nothing but one of the following words:
- core -- the main server
- rlm -- about modules
- documentation
- bts -- bug-tracking problem, suggestions
- website
+ Enable logging in gdb via the following commands:
-After that, you should put a few empty lines, and then describe what the
-problem is and how you think it could best be fixed. Include exact error
-messages, and don't assume the developers know _anything_ about what OS or
-environment you're using.
+ (gdb) set logging file gdb-radiusd.log
+ (gdb) set logging on
-Mailing 'submit' is ONLY for submission of NEW reports. If you have
-follow-up information and you know the bug number, mail
-BUGNUMBER@bugs.freeradius.org (replacing BUGNUMBER with the actual bug
-number, of course).
+ 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.
+
+ You can also submit the information to the bug database at:
+
+ http://bugs.freeradius.org/
+
+ Submitting it to the bug database ensures that the bug report won't
+ get forgotten, and that someone will eventually respond to it.
--
-Chad Miller, FreeRADIUS Project, copyright 2001
-$Revision$
+FreeRADIUS Project, copyright 2004
+$Id$
projects / freeradius.git / blobdiff