From: nolade Date: Wed, 11 Feb 2026 19:35:54 +0000 (-0500) Subject: docs-v4: update & reorg developers/bugs section HIVE 3722 / 3727 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=e60fce623e9686aed3beff669d7d20b8301fa62a;p=thirdparty%2Ffreeradius-server.git docs-v4: update & reorg developers/bugs section HIVE 3722 / 3727 --- diff --git a/doc/antora/modules/ROOT/pages/index.adoc b/doc/antora/modules/ROOT/pages/index.adoc index 2388cf61444..7cfa108a868 100644 --- a/doc/antora/modules/ROOT/pages/index.adoc +++ b/doc/antora/modules/ROOT/pages/index.adoc @@ -84,8 +84,8 @@ even numbered releases should be packaged, e.g. 4.0 or 4.2. xref:developers:coding-methods.adoc[coding standards], xref:developers:coverage.adoc[coverage], and xref:developers:coccinelle.adoc[patches] used when developing. This - guide includes information about xref:developers:bugs.adoc[bugs - reports], and xref:developers:contributing.adoc[contributing] to the + guide includes information about xref:developers:bugs/bugs.adoc[bugs + ], and xref:developers:contributing.adoc[contributing] to the project using GitHub. == Why v4? diff --git a/doc/antora/modules/developers/nav.adoc b/doc/antora/modules/developers/nav.adoc index ec466d5d58d..16e88a0d153 100644 --- a/doc/antora/modules/developers/nav.adoc +++ b/doc/antora/modules/developers/nav.adoc @@ -1,5 +1,10 @@ * xref:index.adoc[Developers] -** xref:bugs.adoc[Bugs] +** xref:bugs/bugs.adoc[Bugs] +*** xref:bugs/coredumps.adoc[Core Dumps] +*** xref:bugs/debugserver.adoc[Debug a Server] +*** xref:bugs/info.adoc[Extract Information] +*** xref:bugs/screen.adoc[Use 'screen'] +*** xref:bugs/valgrind.adoc[Valgrind] ** xref:coding-methods.adoc[Coding Methods] ** xref:coverage.adoc[Code Coverage] ** xref:profile.adoc[Profiling] diff --git a/doc/antora/modules/developers/pages/bugs.adoc b/doc/antora/modules/developers/pages/bugs.adoc deleted file mode 100644 index 7ad843be795..00000000000 --- a/doc/antora/modules/developers/pages/bugs.adoc +++ /dev/null @@ -1,197 +0,0 @@ -= Bugs - -== Introduction - -The FreeRADIUS web site is at https://freeradius.org/, and most -information referenced in this document can be found there. - -This document 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 https://bugs.freeradius.org/, including -information from the debugging sections below. - -For any other issues, you should first discuss them on the -https://freeradius.org/support/[FreeRADIUS 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 https://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 the proceeding section. - -You can also enable the `panic_action` given in -`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 -fxx -``` - -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: - -https://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 https://www.gnu.org/software/screen/[screen] session: `$ 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 (one built with `--enable-developer` as above). -* Configure screen to log to a file by pressing `Ctrl+a`, then `h`. -* Type `gdb /path/to/radiusd` (or /path/to/freeradius on Debian). -* At the `(gdb)` prompt, type `run -X`. -* Detach from screen with `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 2019 - -// Copyright (C) 2025 Network RADIUS SAS. Licenced under CC-by-NC 4.0. -// This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/developers/pages/bugs/bugs.adoc b/doc/antora/modules/developers/pages/bugs/bugs.adoc new file mode 100644 index 00000000000..11036065d0b --- /dev/null +++ b/doc/antora/modules/developers/pages/bugs/bugs.adoc @@ -0,0 +1,148 @@ += Bugs + +If you think you've found a bug, first check to confirm that it's +really a problem. Review the documentation, try to reproduce the bug, +or see if it's a misconfiguration. Once you've confirmed the issue, +you can then report the bug to the development team. Good bug reports +help developers fix problems faster. + +This document 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 https://freeradius.org/[FreeRADIUS] web site also hosts most of the +information referenced in this document. + + +[NOTE] +==== +Do *not* post configuration questions on GitHub, they belong on the +https://freeradius.org/support/[mailing lists] instead. Raising +support requests or questions as a *Defect Report* will result in them +being closed and locked. Repeatedly doing so will lead to you being +banned from the FreeRADIUS project's GitHub repositories. +==== + +== You found a bug + +To report a bug or defect, use the FreeRADIUS GitHub +https://github.com/FreeRADIUS/freeradius-server/issues[Issues] +page. The freeradius-server repository is where development of +FreeRADIUS happens, making it the best place to submit bug reports. + +For example, report a bug when the server terminates ungracefully due +to a bus error, segmentation violation, or other memory +error. Generate the *Defect Report* using the +https://github.com/FreeRADIUS/freeradius-server/issues/new?template=bug.yml[Create +new issue] modal and include information from the debugging sections. + +The https://github.com/FreeRADIUS/freeradius-server/issues/[Issues] +page is for non-security related defect reports. Report security +issues to security@freeradius.org, especially those that can be +exploited from a remote location. This allows patches to be developed +before the issue is made public. This process keeps development +organized and ensures sensitive information is handled properly. + +If the behaviour is correct but confusing, we think that’s a bug too, and +you should file a bug against our documentation. + +For any other issues, discuss them on the +https://www.freeradius.org/list/users.html[FreeRADIUS 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! + +For more information about the users list, the +https://lists.freeradius.org/pipermail/freeradius-users/[lists’ +archives] and the faq, please visit the +https://freeradius.org/support/[support] page. Make sure to READ and +RESPECT the house-rules. You will get much better response and much +faster if you do! + +== Reproduce the bug on current code + +Before reporting a bug, make sure that you're not running an old +version. In many cases, a bug is fixed in a newer release. You can +get the bug fiux by upgrading, rather than submitting a duplicate bug +report. + +Check that the issue still exists in the current released version, and +also the latest version in Git. Check out the latest branch for your +server version, listed on the FreeRADIUS server +https://doc.freeradius.org/[build page]. Once you've switched +branches, build the server from the updated code. + +Next, try to reproduce the issue by following the same steps that +caused the problem. This will check if the defect is still there. It +will also help you give accurate details when you report it. For +instance, if you're working on a feature in version 4.0, check out the +release/4.0 branch and test the issue there. This way, you'll report a +valid defect and help our team fix the issue faster. + +Also, check the +https://github.com/FreeRADIUS/freeradius-server/blob/master/doc/ChangeLog[ChangeLog] +for the stable branch to see if your issue is already fixed. The +ChangeLog is updated as fixes are made to the server code, and usually +reflects the state of the Git HEAD. + +Review the GitHub FreeRADIUS +https://github.com/FreeRADIUS/freeradius-server/issues[Issues] list to +see if your issue has been previously reported. + +== Filing a defect report + +To start, gather information by running the server in +xref:ROOT:debugging/radiusd_X.adoc[debug mode] with radiusd -X to +capture logs. These logs, traces, etc. are needed for diagnosing +issues. Please attach *all* relevant output logs to your report. + +=== Create Issue + +Navigate to the GitHub FreeRADIUS +https://github.com/FreeRADIUS/freeradius-server/issues[Issues] page +and click "New Issue" to generate a *Defect Report*. Provide all the +requested details including a descriptive title that summarizes the +bug or behaviour. + +*Type of bug/defect* + +Choose the correct type of bug/defect from the category list. By +selecting the right category, developers can find the root cause and +take the right action to fix it. This helps keep the FreeRADIUS +codebase stable, secure, and working as expected. + +.Type of Bug or Defect +[options=header, cols="20,~",autowidth] +|=== +| Category | Description +| Crash or memory corruption | This happens when the system or app suddenly stops working or doesn't respond. +| Non-compliance | Occurs when a system or application does not meet the required standards or regulations. For example, if a new attribute is incorrectly designed, it may not comply with RFC standards. The last category is unexpected behaviour. This applies when the issue is apparent or has been validated by a project member. +| incorrect 3rd party API usage | The application programming interface is not used as intended. It can lead to errors or unexpected behaviour. +| Unexpected behaviour | If the issue is obvious or has been validated by a project member. +|=== + +*Steps to reproduce* + +Explain how to reproduce the bug using clear, step-by-step +instructions. Please provide details about your environment. Include +the operating system, version, platform, and any configuration changes +made. Describe what you expected to happen and what actually happened. + +*Log outputs* + +When filing a bug report, you need to include logs. Please attach the +relevant debug logs or stack traces, along with any output from +debugging you did. The following techniques are avaiable to help you +debug FreeRADIUS: + +* xref:bugs/coredumps.adoc[Core Dumps] +* xref:bugs/debugserver.adoc[Debug a Live Server] +* xref:bugs/info.adoc[Obtain Useful Information] +* xref:bugs/screen.adoc[Use `screen`] +* xref:bugs/valgrind.adoc[Valgrind] + +// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0. +// This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/developers/pages/bugs/coredumps.adoc b/doc/antora/modules/developers/pages/bugs/coredumps.adoc new file mode 100644 index 00000000000..e69d4c2350c --- /dev/null +++ b/doc/antora/modules/developers/pages/bugs/coredumps.adoc @@ -0,0 +1,41 @@ += 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 the xref:bugs/info.adoc[Extract Information]] section. + +You can also enable the `panic_action` given in +`radiusd.conf`. See the comments in that file for more details +about automatically collecting gdb debugging information when the server +crashes. + + +// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0. +// This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/developers/pages/bugs/debugserver.adoc b/doc/antora/modules/developers/pages/bugs/debugserver.adoc new file mode 100644 index 00000000000..345c80c681c --- /dev/null +++ b/doc/antora/modules/developers/pages/bugs/debugserver.adoc @@ -0,0 +1,50 @@ += Debug a 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 +xref:bugs/coredumps.adoc[Core Dumps] 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 -fxx +``` + +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) +``` + +Next, follow the instructions in the xref:developers:bugs/info.adoc[Extract Information]. + +// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0. +// This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/developers/pages/bugs/info.adoc b/doc/antora/modules/developers/pages/bugs/info.adoc new file mode 100644 index 00000000000..d92391a21d7 --- /dev/null +++ b/doc/antora/modules/developers/pages/bugs/info.adoc @@ -0,0 +1,42 @@ += Extract 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. + +Submit the information from the log file, along with any log output +files, the output of `radiusd -xv`, and the required information about +your environment to the GitHub FreeRADIUS +https://github.com/FreeRADIUS/freeradius-server/issues[Issues] page. + +Submit all the *required* logs and relevant information with your +xref:bugs/bugs.adoc#CreateIssue[Issue Defect Report]. + +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. + +// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0. +// This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/developers/pages/bugs/screen.adoc b/doc/antora/modules/developers/pages/bugs/screen.adoc new file mode 100644 index 00000000000..765c1726981 --- /dev/null +++ b/doc/antora/modules/developers/pages/bugs/screen.adoc @@ -0,0 +1,25 @@ += Use `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 https://www.gnu.org/software/screen/[screen] session: `$ 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 (one built with `--enable-developer` as above). +* Configure screen to log to a file by pressing `Ctrl+a`, then `h`. +* Type `gdb /path/to/radiusd` (or /path/to/freeradius on Debian). +* At the `(gdb)` prompt, type `run -X`. +* Detach from screen with `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. + + + +// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0. +// This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/developers/pages/bugs/valgrind.adoc b/doc/antora/modules/developers/pages/bugs/valgrind.adoc new file mode 100644 index 00000000000..407591adc58 --- /dev/null +++ b/doc/antora/modules/developers/pages/bugs/valgrind.adoc @@ -0,0 +1,16 @@ += 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. + +// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0. +// This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/developers/pages/index.adoc b/doc/antora/modules/developers/pages/index.adoc index 665c177f035..0621b29d15d 100644 --- a/doc/antora/modules/developers/pages/index.adoc +++ b/doc/antora/modules/developers/pages/index.adoc @@ -1,4 +1,3 @@ - = FreeRADIUS Development As the name suggests, FreeRADIUS is developed under the GNU General Public License, Version 2 (GPLv2). We invite anyone to use and contribute code to the project. The following information should be helpful to those who want to contribute. @@ -18,7 +17,7 @@ development list]. This list is highly technical and isn't for most users of the interested in writing software for the new server. For normal discussion of the server and how to use it, subscribe to the https://lists.freeradius.org/mailman/listinfo/freeradius-users[FreeRADIUS user-list]. -== xref:bugs.adoc[Bugs] +== xref:bugs/bugs.adoc[Bugs] If the server crashes due to memory errors, report it to the issue tracker with debugging info. For other issues, discuss them on the users mailing list.