+++ /dev/null
-BUGS
-
-0. INTRODUCTION
-
- 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!
-
-
-1. YOU FOUND A BUG
-
- Where the server terminates ungracefully due to a bus error,
- segmentation violation, or other memory error, you should create
- a new issue in the issue tracker <URL: http://bugs.freeradius.org>,
- including information from sections 4 and 5.
-
- For other issues, you should first discuss them on the users list,
- to see if anyone can reproduce them. 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.
-
- 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!
-
-
-2. CORE DUMPS
-
- If the server, or one of the accompanying programs core dumps, then
- you should rebuild the server as follows:
-
- $ ./configure --enable-developer
- $ make
- $ make install
-
- and then run the program again. You may have to to enable core
- dumps, via:
-
- $ ulimit -c unlimited
-
- When it core dumps, do:
-
- $ gdb /path/to/executable /path/to/core/file
-
- Enable logging in gdb via the following commands:
-
- (gdb) set logging file gdb-radiusd.log
- (gdb) set logging on
-
- and follow the instructions in section 4, below.
-
- You can also enable the "panic_action" given in raddb/radiusd.conf.
- See the comments in that file for more details about automatically
- collecting gdb debugging information when the server crashes.
-
-
-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. For debugging, you probably want to do:
-
- (gdb) set args -f
-
- 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
-
- Once you have a core dump loaded into gdb, or FreeRADIUS running under
- gdb, you may use the commands below to get useful information about
- the state of the server.
-
- 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.
-
- You should then submit the information from the log file, along with
- any server output, the output of radiusd -xv, and information about your
- operating system to:
-
- http://bugs.freeradius.org/
-
- Submitting it to the bug database ensures that the bug report won't
- get forgotten, and that it will be dealt with in due course.
-
- You should provide the issue number in any mail sent to the user's list.
-
-
-5. VALGRIND
-
- On Linux systems, "valgrind" is a useful tool that can catch certain
- classes of bugs. To use it, run the server via:
-
-$ 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 (https://www.gnu.org/software/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 2014
-$Id$
--- /dev/null
+# Introduction
+
+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!
+
+# You Found A Bug
+
+Where the server terminates ungracefully due to a bus error,
+segmentation violation, or other memory error, you should create
+a new issue in the issue tracker <URL: http://bugs.freeradius.org>,
+including information from sections 4 and 5.
+
+For other issues, you should first discuss them on the users list,
+to see if anyone can reproduce them. 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.
+
+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!
+
+# Core Dumps
+
+If the server, or one of the accompanying programs core dumps, then
+you should rebuild the server as follows:
+
+ $ ./configure --enable-developer
+ $ make
+ $ make install
+
+and then run the program again. You may have to to enable core
+dumps, via:
+
+ $ ulimit -c unlimited
+
+When it core dumps, do:
+
+ $ gdb /path/to/executable /path/to/core/file
+
+Enable logging in `gdb` via the following commands:
+
+ (gdb) set logging file gdb-radiusd.log
+ (gdb) set logging on
+
+and follow the instructions in section 4, below.
+
+You can also enable the "panic_action" given in raddb/radiusd.conf.
+See the comments in that file for more details about automatically
+collecting gdb debugging information when the server crashes.
+
+# 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. For debugging, you probably want to do:
+
+ (gdb) set args -f
+
+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 the next section.
+
+# Obtaining Useful Information
+
+Once you have a core dump loaded into gdb, or FreeRADIUS running under
+gdb, you may use the commands below to get useful information about
+the state of the server.
+
+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.
+
+You should then submit the information from the log file, along with
+any server output, the output of radiusd -xv, and information about your
+operating system to:
+
+http://bugs.freeradius.org/
+
+Submitting it to the bug database ensures that the bug report won't
+get forgotten, and that it will be dealt with in due course.
+
+You should provide the issue number in any mail sent to the user's list.
+
+# Valgrind
+
+On Linux systems, "valgrind" is a useful tool that can catch certain
+classes of bugs. To use it, run the server via:
+
+ $ 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.
+
+# 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 (https://www.gnu.org/software/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 2014
+$Id$
projects / thirdparty / freeradius-server.git / commitdiff
