5 The FreeRADIUS web site is at <URL: http://www.freeradius.org>, and
6 most information referenced in this document can be found there.
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!
15 So you think you've found a bug in the FreeRADIUS server?
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!
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.
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!
33 If the server, or one of the accompyaning programs core dumps, then
34 you should rebuild the server as follows:
36 $ ./configure --enable-developer
40 and then run the program again. You may have to to enable core
45 When it core dumps, do:
47 $ gdb /path/to/executable /path/to/core/file
49 Enable logging in gdb via the following commands:
51 (gdb) set logging file gdb-radiusd.log
54 and follow the instructions in section 4, below.
56 3. DEBUGGING A LIVE SERVER
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:
66 Enable logging in gdb via the following commands:
68 (gdb) set logging file gdb-radiusd.log
71 Tell gdb to pass any necessary command-line arguments to the
76 Where the "..." are the command-line arguments you normally pass to
77 radiusd. If you don't normally pass command-line arguments, this
78 line is not necessary.
84 When something interesting happens, you can hit CTRL-C in the
85 window, and you should be back at the gdb prompt:
89 And follow the instructions in section 4, below.
91 4. OBTAINING USEFUL INFORMATION
93 If the server was built with threads, you can do:
97 Which will give you information about the threads. If the server
98 isn't threaded, that command-line will print a message saying so.
102 (gdb) thread apply all bt full
104 If the server isn't threaded, the "thread apply" section isn't necessary
106 The output should be printed to the screen, and also sent to the
107 gdb-radiusd.log file. Copy the log gile and mail it to the list, or
108 put it on a web page if it's too large. Include the name of the
110 Without this information, it's impossible for anyone to know why the
113 You can also submit the information to the bug database at:
115 http://bugs.freeradius.org/
117 Submitting it to the bug database ensures that the bug report won't
118 get forgotten, and that someone will eventually respond to it.
123 On Linux systems, "valgrind" is a useful tool that can catch certain
124 classes of bugs. To use it, run the server voa:
126 $ valgrind --tool=memcheck --leak-check=full radiusd -Xm
128 It will print out certain kinds of errors to the screen. There may
129 be a number of errors related to OpenSSL, dlopen(), or libtldl. We
130 cannot do anything about those problems. However, any errors that are
131 inside of the FreeRADIUS source should be brought to our attention.
134 6. Running with "screen"
136 If the bug is a crash of the server, and it takes a long time for the
137 crash to happen, perform the following steps:
140 * open a screen session (http://blogamundo.net/code/screen/)
142 * make sure FreeRADIUS is not running
143 * make sure you have all the debug symbols about, or a debugable
144 version of the server installed
145 * configure screen to log to a file; 'Ctrl-A H'
146 * type 'gdb /path/to/radius' (or /path/to/freeradius on Debian)
147 * at the (gdb) prompt, type 'run -X'
148 * detach from screen 'Ctrl-A D'
149 * when you notice FreeRADIUS has died, reconnect to your screen session
151 * at the (gdb) prompt type 'where' or for *lots* of info try
152 'thread apply all bt full'
153 * tell screen to stop logging, 'Ctrl-A H'
158 FreeRADIUS Project, copyright 2008