From: Alan T. DeKok Date: Wed, 1 Feb 2017 19:35:07 +0000 (-0500) Subject: update for prettiness X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=bacdaa40ddfe1e60e282500a8369fe800b97d955;p=thirdparty%2Ffreeradius-server.git update for prettiness --- diff --git a/doc/bugs b/doc/bugs deleted file mode 100644 index d299f0fe3b1..00000000000 --- a/doc/bugs +++ /dev/null @@ -1,175 +0,0 @@ -BUGS - -0. INTRODUCTION - - The FreeRADIUS web site is at , 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 , - 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$ diff --git a/doc/bugs.md b/doc/bugs.md new file mode 100644 index 00000000000..8a9943d1d26 --- /dev/null +++ b/doc/bugs.md @@ -0,0 +1,166 @@ +# Introduction + +The FreeRADIUS web site is at , 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 , +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$