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!
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.
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!
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.
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!
38 If the server, or one of the accompanying programs core dumps, then
39 you should rebuild the server as follows:
41 $ ./configure --enable-developer
45 and then run the program again. You may have to to enable core
50 When it core dumps, do:
52 $ gdb /path/to/executable /path/to/core/file
54 Enable logging in gdb via the following commands:
56 (gdb) set logging file gdb-radiusd.log
59 and follow the instructions in section 4, below.
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.
66 3. DEBUGGING A LIVE SERVER
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:
76 Enable logging in gdb via the following commands:
78 (gdb) set logging file gdb-radiusd.log
81 Tell gdb to pass any necessary command-line arguments to the
86 Where the "..." are the command-line arguments you normally pass to
87 radiusd. For debugging, you probably want to do:
95 When something interesting happens, you can hit CTRL-C in the
96 window, and you should be back at the gdb prompt:
100 And follow the instructions in section 4, below.
103 4. OBTAINING USEFUL INFORMATION
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.
109 If the server was built with threads, you can do:
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.
118 (gdb) thread apply all bt full
120 If the server isn't threaded, the "thread apply" section isn't necessary
122 The output should be printed to the screen, and also sent to the
123 gdb-radiusd.log file.
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
129 http://bugs.freeradius.org/
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.
134 You should provide the issue number in any mail sent to the user's list.
139 On Linux systems, "valgrind" is a useful tool that can catch certain
140 classes of bugs. To use it, run the server voa:
142 $ valgrind --tool=memcheck --leak-check=full radiusd -Xm
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.
150 6. RUNNING WITH "SCREEN"
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:
156 * open a screen session (https://www.gnu.org/software/screen/)
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
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'
174 FreeRADIUS Project, copyright 2014